Draft: docs: Auto-generate README.md from meta files

[spetrosi]

Add a documentation generation system that produces README.md from three YAML inputs: meta/main.yml, meta/argument_specs.yml (with doc_tags for variable grouping), and meta/docs_specs.yml (defining scenarios, notes, returns, and examples).

Variables are rendered as readable plain markdown with blockquote nesting for sub-options. Inline anchor tags enable cross-references between variables.

Includes three HTML previews generated from README.md for comparison:

• README.html: Ansible-themed, generated with pandoc and custom CSS
• README_github.html: GitHub-styled, generated with the existing .pandoc_template.html5 template
• sphinx_html/bootloader_role.html: Official Ansible Sphinx output via antsibull-docs with modifications to include our custom doc sections — closest to official Ansible docs but requires a complex build pipeline

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: linux-system-roles/bootloader/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 4127b299-d4df-4215-b6c8-45a633cf0ef2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

CI tests do not run automatically on pull requests. A role repository
maintainer can start them by posting a /citest slash command in a
pull request comment.

See GitHub CI testing using /citest
for details.

Run every available CI workflow:

/citest all

Run the linting and other lightweight checks:

/citest linters

Run the integration tests (QEMU/container and Testing Farm):

/citest integration

Run one or more selected workflows by separating their names with spaces:

/citest ansible-lint
/citest ansible-lint markdownlint

Command	Check name	Description
/citest all	All checks listed below	Run every CI test available for this role
/citest linters	Lint and lightweight checks	Run ansible-lint, ansible-test, ansible-managed-var-comment, codespell, markdownlint, pr-title-lint, test_converting_readme, and codeql, python-unit-test, and shellcheck when those workflows exist
/citest integration	QEMU/container and Testing Farm checks	Run qemu-kvm-integration-tests and tft
/citest ansible-lint	Ansible Lint / ansible_lint (<ansible-lint>, <ansible>, <python>) (pull_request)	Lint Ansible content after converting the role to collection format
/citest ansible-managed-var-comment	Check for ansible_managed variable use in comments / ansible_managed_var_comment (pull_request)	Fail if ansible_managed is used in comments
/citest ansible-test	Ansible Test / ansible_test (<ansible>, <python>) (pull_request)	Run ansible-test sanity tests
/citest codespell	Codespell / Check for spelling errors (pull_request)	Check for spelling errors
/citest markdownlint	Markdown Lint / markdownlint (pull_request)	Lint Markdown files
/citest pr-title-lint	PR Title Lint / commit-checks	Check that the pull request title follows the required format
/citest qemu-kvm-integration-tests	Test / scenario (<image>, <env>) (pull_request)	Run role integration tests in QEMU VMs and containers
/citest test_converting_readme	Test converting README.md to README.html / test_converting_readme (pull_request)	Convert README.md to HTML
/citest tft	<platform>|ansible-<version>	Run integration tests in Testing Farm
/citest woke	Woke / Detect non-inclusive language (pull_request)	Detect non-inclusive language
/citest codeql	CodeQL / Analyze (python) (pull_request)	CodeQL security and quality analysis for Python
/citest python-unit-test	Python Unit Tests / python (<python>, <os>) (pull_request)	Run Python unit tests

Post another /citest comment at any time to run another selection.

[spetrosi]

@richm please take a look. So the plan is to make developers update meta/argument_specs.yml and meta/doc_specs.yml when they do changes to roles variables. Then, there is a script that generates a README.md from three meta/ files.
Then, pandoc converts the README.md to README.html with an Ansible-like CSS template.

What's new:
doc_specs include extra information for the role, like available scenarios, notes, return variables.
argument_specs includes a new field doc_tag that tags each parameter to one or more scenarios. These then appear in the doc. For bootloader, these are general, security, reboot. I want to make it similar to how mssql README is structured. I think it's good for users to see a scenario that they are interested in and view what variables are there. Each scenario also has one or more example playbooks.

[spetrosi]

/citest linters