docs: draft preview of generated documentation from meta/argument_specs.yml

[spetrosi]

Note

Draft preview of a new documentation format — not a final change.
This stacks on top of #913 (the argument spec), so the diff here includes
those commits. Review only the docs commit (docs: draft preview ...).

Generate the role's documentation from the native meta/argument_specs.yml
using an antsibull-docs + Sphinx pipeline, making the argument spec the single
source of truth with no hand-maintained README templates or markup to keep in
sync.

meta/argument_specs.yml carries the full page using only the native fields
antsibull renders: short_description and a description list (Synopsis),
options (Parameters), custom platform/architectures attributes
(Attributes), notes, examples, and author. Backtick text was converted
to Ansible semantic markup: C(), V(), O(), B(), L(). The prose is
written to technical-documentation standards: active voice, concise, and
unambiguous.

Build pipeline (.build_docs.sh)

Stages the role into a temporary fedora.linux_system_roles collection, runs
antsibull-docs to produce RST, renders it with Sphinx to HTML, then converts
that HTML to Markdown. It creates, at the repo root:

• README.md the role's main README — read directly as plain text in
  the repo and rendered by Markdown viewers (GitHub, Ansible
  Galaxy, Red Hat Automation Hub, which display role docs only
  as Markdown)
• README.html symlink to the styled page in sphinx_html/
• sphinx_html/ the Sphinx HTML site plus its _static assets

README.md is produced from the Sphinx HTML by .html_to_md.py (antsibull has
no Markdown output). The prose is a pandoc HTML → GFM conversion; the Parameters
and Attributes tables are rebuilt as real Markdown pipe tables, with option
nesting encoded as bullet markers (Galaxy strips the CSS classes antsibull uses
for indentation) and columns space-aligned so the table reads well as plain
text.

The HTML output (README.html + sphinx_html/) is included only to preview
the styled page in this draft. The bundled fonts are trimmed to just the
FontAwesome icon font (~0.95MB total), which has no system fallback; the RTD
theme's text fonts fall back to the system sans-serif and are dropped. Long
term the full styled site would be built once for the whole collection, not per
role, to keep each role repo small.

🤖 Generated with Claude Code

[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
/citest shellcheck	ShellCheck / shellcheck (pull_request)	Lint shell scripts

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

[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/network/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: f635e2d2-f21e-42a3-9525-314f26069664

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

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}