Skip to content

docs: generate the documented command line help from the parsers - #316

Merged
jdhughes-dev merged 3 commits into
developfrom
docs-usage
Aug 11, 2026
Merged

docs: generate the documented command line help from the parsers#316
jdhughes-dev merged 3 commits into
developfrom
docs-usage

Conversation

@jdhughes-dev

Copy link
Copy Markdown
Collaborator

The usage and option blocks in the README and the docs are the --help output of a command, which was edited by hand and had gone stale: the -fc/-cc option lists were the choices removed when a version suffix was allowed, make-program listed zonbud3 rather than zonbud, and getting_started used the argparse heading from before python 3.10.

The blocks are now written by scripts/update_docs.py (pixi run update-docs), and test_docs_current asserts they match the parsers. The parser for each command is split out of the function that runs it so the help can be rendered without parsing arguments.

The usage and option blocks in the README and the docs are the --help
output of a command, which was edited by hand and had gone stale. The
option lists for -fc and -cc were the choices removed when a version
suffix was allowed, make-program listed zonbud3 rather than zonbud, and
getting_started used the argparse heading from before python 3.10.

The blocks are now written by scripts/update_docs.py, which is run with
'pixi run update-docs'. A test asserts the blocks match the parsers, so a
change to an argument that is not documented fails.

The parser for each command is split out of the function that runs it so
that the help can be rendered without parsing arguments.
@codecov

codecov Bot commented Aug 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 75.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.264%. Comparing base (5f1fdc5) to head (a71ecf6).
⚠️ Report is 2 commits behind head on develop.

Files with missing lines Patch % Lines
pymake/cmds/build.py 71.428% 2 Missing ⚠️
pymake/cmds/mfpymakecli.py 75.000% 1 Missing ⚠️
pymake/pymake_parser.py 80.000% 1 Missing ⚠️
Additional details and impacted files
@@              Coverage Diff              @@
##           develop      #316       +/-   ##
=============================================
+ Coverage   79.671%   81.264%   +1.593%     
=============================================
  Files           20        20               
  Lines         3591      3779      +188     
=============================================
+ Hits          2861      3071      +210     
+ Misses         730       708       -22     
Files with missing lines Coverage Δ
pymake/cmds/mfpymakecli.py 64.705% <75.000%> (+64.705%) ⬆️
pymake/pymake_parser.py 81.250% <80.000%> (+45.766%) ⬆️
pymake/cmds/build.py 53.061% <71.428%> (+53.061%) ⬆️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jdhughes-dev
jdhughes-dev merged commit 6e789b1 into develop Aug 11, 2026
23 checks passed
@jdhughes-dev
jdhughes-dev deleted the docs-usage branch August 11, 2026 22:50
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