Improve man page generation - #9478
Open
rokm wants to merge 4 commits into
Open
Conversation
rokm
force-pushed
the
improve-manpage-generation
branch
from
July 9, 2026 19:57
eb754dd to
8a2b1de
Compare
Rewrite the `help2rst` module and its `parser_to_rst()` function. Instead of havign the parser instance format full help message and trying to parse it with regex, the new implementation tries to instead extract the relevant bits of text from the parser itself (i.e., group titles, option strings, help strings), based on `argparse`'s formatter implementation. As a shortcut, the option argument strings are currently formatted using `argparse`'s formatter and its internal helpers, but if that proves to be too unstable, we can implement the equivalent parts ourselves.
If `.. option::` directive is enabled, have `help2rst.parser_to_rst()` escape curly braces in generated argument string, and wrap the whole argument stirng in (unescaped) curly braces, so they become "option placeholders". This allows us to use `option_emphasise_placeholders` option, which was added in `sphinx` 5.1 [1]. [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-option_emphasise_placeholders
Enable option directive when dumping CLI options for man(ual) pages.
This fixes identification and stylization of the option argument(s)
string, regardless of whether option has multiple names, is a
choice-based option that lists all valid values inside curly brackets,
or has an argument string that contains a colon.
It also makes the manual pages that end up embedded in the docs
("Man Pages" section) look consistent with the "Using PyInstaller"
section.
Extend the `help2rst.parser_to_rst()` helper to automatically add notes to command-line options that are disallowed when building from a .spec file.
rokm
force-pushed
the
improve-manpage-generation
branch
from
July 9, 2026 20:05
8a2b1de to
2d48d8a
Compare
Member
|
Hmm, I think I'm ok with 2d48d8a. It is everywhere but I find it less distracting than I'd expect to find it. But we do also have a fast-exiting runtime error for it so I don't think anyone loses much by not getting it from the documentation. |
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.
Turns out that some of the CLI options documented in our manual pages (both those embedded in the docs and stand-alone versions) end up mangled due to special formatting of the argument/value part.
See
--add-dataand--add-binaryunder What To Bundle, Where To Search, or--debugunder How to Generate.Their counterparts in the "Using PyInstaller" section fare better, because they are using the
.. option::directive.This PR tries to remedy the situation by using
.. option::directive for both regular documentation and manual pages; it also wraps the argument/value string in curly braces, for enabled emphasis viaoption_emphasise_placeholders.It also rewrites the
help2rstmodule and itsparser_to_rst()function. Instead of having parser emit complete help message and then trying to parse it, we now try to directly collect the relevant bits of text from the parser and its elements(action groups and actions inside them). This gives us more control over formatting, although as a shortcut, the internals of
argparse.HelpFormatterare still currently used to format various types of argument/value; if this proves problematic/unstable, we could implement our own equivalents for the limited amount of argument types that we use in our CLIs.Direct handling of parser options also allows us to implement additional tricks, such as adding
"This option is not allowed when building from .spec file."note to all makespec options - see 08cd3db. Whether we'd actually want to do that or not is still up to debate, though; it seemed like an interesting idea to try to implement, but that note ended up attached to almost every option...