🐛 fix(docs): auto-generate manpage from CLI parser#3911
Merged
gaborbernat merged 9 commits intotox-dev:mainfrom Mar 30, 2026
Merged
🐛 fix(docs): auto-generate manpage from CLI parser#3911gaborbernat merged 9 commits intotox-dev:mainfrom
gaborbernat merged 9 commits intotox-dev:mainfrom
Conversation
The static RST manpage had broken section headers (all top-level `####` overlines) producing empty `.TH` metadata and missing `.SH` sections. It also only documented 6 of 11 commands and a subset of options. Generate the manpage RST from the actual argparse parser at wheel build time so commands and options stay in sync automatically. Tests validate troff output structure and verify all parser commands/options appear.
The static RST manpage had broken section headers (all top-level `####` overlines) producing empty `.TH` metadata and missing `.SH` sections. It also only documented 6 of 11 commands and a subset of options. Regenerate the RST with proper heading hierarchy from the argparse parser via `tools/generate_manpage.py`. The build hook reads the static file (avoiding runtime deps at build time), while tests verify the file stays in sync with the actual CLI. Added changelog fragment.
rahuldevikar
approved these changes
Mar 30, 2026
Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
for more information, see https://pre-commit.ci
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The static RST manpage shipped broken section headers — all sections used top-level
####overlines instead of subsection underlines, producing an empty.THheader and missing.SHdirectives in the generated troff. The manpage also only documented 6 of the 11 available commands and omitted most global options like--colored,--root,--version, and--no-provision. 📄The manpage RST is now generated at wheel build time from the actual argparse parser via
_get_parser_doc(). Commands, aliases, and options are extracted directly from the parser so the manpage stays in sync with the CLI automatically. Static sections (FILES, ENVIRONMENT VARIABLES, SEE ALSO, AUTHOR) remain hand-written since they document things outside the parser. The docutilswriter_nameparameter was also updated to the non-deprecatedwriterform.The static
docs/man/tox.1.rstand the unused Sphinxman_pagesconfig have been removed since the wheel build hook now owns manpage generation entirely. 🧪 Tests validate both the troff structure (.THmetadata,.SHsections, Name content) and that every parser command and option appears in the output.Fixes #3878