Skip to content

ci: Prepare for README files generated from argument_specs and extra_specs - #248

Merged
spetrosi merged 1 commit into
mainfrom
ci-docs-from-specs
Nov 13, 2026
Merged

spetrosi merged 1 commit into
mainfrom
ci-docs-from-specs

Conversation

@spetrosi

Copy link
Copy Markdown
Contributor

Generating README.md and README.html from meta/argument_specs.yml and meta/extra_specs.yml has the following advantages:

  1. A single source of truth - developers need to manage all information in specs files only.
  2. Ansible-themed README familiar to Ansible users.

This PR adds:

  • Distribute check-docs-updated.yml, a workflow_call check wired into citest that runs tox -e build-docs and fails if the committed README files are out of date; also add it to the citest known/linters lists and the /citest instructions table
  • Retire the old pandoc docs mechanism: remove build_docs.yml, test_converting_readme.yml and .pandoc_template.html5, and drop test_converting_readme from citest and its instructions
  • Skip README CI-badge injection: the generated README carries no badges (the per-check workflows are workflow_call-only and cannot show a meaningful status badge, and an injected badge would also break the check-docs regenerate-and-diff)
  • Add a workflow that publishes docs to GH pages for roles that generate README from specs
  • Make codespell ignore README.html instead of .README.html

Signed-off-by: Sergei Petrosian spetrosi@redhat.com

…specs

Generating README.md and README.html from meta/argument_specs.yml and meta/extra_specs.yml has the following advantages:
1. A single source of truth - developers need to manage all information in specs files only.
2. Ansible-themed README familiar to Ansible users.

This PR adds:
* Distribute check-docs-updated.yml, a workflow_call check wired into citest that runs `tox -e build-docs` and fails if the committed README files are out of date; also add it to the citest known/linters lists and the /citest instructions table
* Retire the old pandoc docs mechanism: remove build_docs.yml, test_converting_readme.yml and .pandoc_template.html5, and drop test_converting_readme from citest and its instructions
* Skip README CI-badge injection: the generated README carries no badges (the per-check workflows are workflow_call-only and cannot show a meaningful status badge, and an injected badge would also break the check-docs regenerate-and-diff)
* Add a workflow that publishes docs to GH pages for roles that generate README from specs
* Make codespell ignore README.html instead of .README.html

Signed-off-by: Sergei Petrosian <spetrosi@redhat.com>
@spetrosi
spetrosi requested a review from richm as a code owner November 13, 2026 13:50
@spetrosi spetrosi self-assigned this Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026

Copy link
Copy Markdown

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

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
  • Autofix · 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

@github-actions

Copy link
Copy Markdown

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

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

@spetrosi
spetrosi merged commit 6ccb870 into main Nov 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant