Harden generated docs CI checks

[koxudaxi]

Summary by CodeRabbit

• Chores
  • Updated CI/CD workflows to validate pre-generated documentation and schemas instead of generating them during builds, improving consistency checks and reducing build times.

[coderabbitai]

Walkthrough

This PR converts CI/CD workflows to validate pre-generated documentation and prompt data instead of generating them, while reducing Git checkout depth across multiple workflow files.

Changes

Cohort / File(s)	Summary
Workflow Documentation Validation .github/workflows/cli-docs.yml, .github/workflows/llms-txt.yml, .github/workflows/schema-docs.yml	Remove full Git history checkout (fetch-depth: 0) and add --check flag to documentation generation scripts, switching from generation to validation mode.
README Workflow Changes .github/workflows/readme.yml, .github/workflows/test.yml	Remove full Git history checkout and update tox invocations to run in check mode instead of update mode; consolidate README setup and validation steps.
Tox Environment Extensions tox.ini	Extend cli-docs testenv to invoke build_prompt_data.py with passthrough arguments; extend readme testenv to validate markdown command help consistency via update_command_help_on_markdown.py.

Possibly Related PRs

• PR #538: Directly modifies the same CI workflow files and tox configuration to switch from generation to validation/check mode with adjusted checkout behavior.
• PR #517: Modifies identical CI/workflow and documentation generation steps referenced in this PR.
• PR #539: Introduces changes to scripts/build_prompt_data.py and related script signatures that align with the --check flag additions in this PR's workflow changes.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hop, skip, and a validation check,
No fetch-depth depths—just what's on deck,
Generation's out, verification's in,
The workflows dance to docs' true spin! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Harden generated docs CI checks' clearly and concisely describes the main change: converting CI workflows to validate pre-generated documentation instead of generating/updating it.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch harden-generated-docs-ci-checks

---

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 and usage tips.}

[github-actions]

📚 Docs Preview: https://pr-551.fastapi-code-generator.pages.dev

[codspeed-hq]

Merging this PR will degrade performance by 11.44%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_generate_default_template_benchmark	48.7 ms	55 ms	-11.44%

---

_{Comparing harden-generated-docs-ci-checks (b2a5686) with main (a491d30)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (a491d30) to head (b2a5686).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #551   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           16        16           
  Lines         1012      1012           
  Branches       110       110           
=========================================
  Hits          1012      1012           

Flag	Coverage Δ
unittests	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tox.ini (1)

57-58: Posargs default consistency (optional).

cli-docs uses {posargs} (no default), while readme (Line 67) and config-types (Line 91) use {posargs:--check}. Both posargs are correctly passed to all sub-scripts in their respective envs, but the inconsistent default means tox -e cli-docs runs in build mode by default while tox -e readme / tox -e config-types validate by default. If the intent is "build by default locally, check in CI", consider documenting it; otherwise unifying on {posargs:--check} would make local invocation safer.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tox.ini` around lines 57 - 58, Unify the posargs default for consistency:
update the tox env "cli-docs" so its invocations of scripts/build_cli_docs.py
and scripts/build_prompt_data.py use {posargs:--check} like the "readme" and
"config-types" envs (or alternatively add a short comment documenting the
intended behavior if you intentionally want different defaults); target the
"cli-docs" env entries that call scripts/build_cli_docs.py and
scripts/build_prompt_data.py and change their {posargs} usage to
{posargs:--check} (or add the explanatory comment) so local and CI behavior is
consistent and safer.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/cli-docs.yml:
- Around line 42-44: Remove the --check flag from the workflow run steps that
call the generation scripts: change the run commands invoking
".tox/cli-docs/bin/python scripts/build_cli_docs.py --check" and
".tox/cli-docs/bin/python scripts/build_prompt_data.py --check" so they call the
scripts without the --check argument (i.e., ".tox/cli-docs/bin/python
scripts/build_cli_docs.py" and ".tox/cli-docs/bin/python
scripts/build_prompt_data.py"); this ensures the jobs run in write/build mode
consistent with the CI design and the generated-docs-sync.yml pattern.

---

Nitpick comments:
In `@tox.ini`:
- Around line 57-58: Unify the posargs default for consistency: update the tox
env "cli-docs" so its invocations of scripts/build_cli_docs.py and
scripts/build_prompt_data.py use {posargs:--check} like the "readme" and
"config-types" envs (or alternatively add a short comment documenting the
intended behavior if you intentionally want different defaults); target the
"cli-docs" env entries that call scripts/build_cli_docs.py and
scripts/build_prompt_data.py and change their {posargs} usage to
{posargs:--check} (or add the explanatory comment) so local and CI behavior is
consistent and safer.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fcdd5330-8619-453f-ba77-8912526b2a58

📥 Commits

Reviewing files that changed from the base of the PR and between a491d30 and b2a5686.

📒 Files selected for processing (6)

• .github/workflows/cli-docs.yml
• .github/workflows/llms-txt.yml
• .github/workflows/readme.yml
• .github/workflows/schema-docs.yml
• .github/workflows/test.yml
• tox.ini

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Look for --check argument handling in the two scripts
fd -t f -E '*test*' 'build_cli_docs.py|build_prompt_data.py' | xargs -I{} sh -c 'echo "===== {} ====="; rg -nP -C2 "(--check|\"check\"|args\.check|argparse|parse_args)" "{}"'

Repository: koxudaxi/fastapi-code-generator

Length of output: 1270

---

Remove --check from this workflow—it conflicts with the project's CI design.

Both build_cli_docs.py and build_prompt_data.py do support the --check flag and properly exit non-zero on drift. However, this workflow should run these scripts in write/build mode (without --check), not check mode. PR jobs verify only that generation succeeds; the syncing of updated tracked files is delegated to generated-docs-sync.yml, which runs on main after merge. This pattern is consistent with the project's design philosophy and datamodel-code-generator. Run the scripts without --check on line 42 and line 44.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/cli-docs.yml around lines 42 - 44, Remove the --check flag
from the workflow run steps that call the generation scripts: change the run
commands invoking ".tox/cli-docs/bin/python scripts/build_cli_docs.py --check"
and ".tox/cli-docs/bin/python scripts/build_prompt_data.py --check" so they call
the scripts without the --check argument (i.e., ".tox/cli-docs/bin/python
scripts/build_cli_docs.py" and ".tox/cli-docs/bin/python
scripts/build_prompt_data.py"); this ensures the jobs run in write/build mode
consistent with the CI design and the generated-docs-sync.yml pattern.