-
-
Notifications
You must be signed in to change notification settings - Fork 512
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Ship a better/proper manpage #1409
Comments
streamlink has an interesting version of an argparse plugin. I think it could probably be simplified further for tox (e.g. no argument groups I think?) and used instead of autoprogram to generate a head-less usage section, to be embedded into rst templates such as the above. |
I think with the looming tox 4 (#1400) we'll need to reconsider this. |
Hi there! I packaged argparse-cli for Debian for the purposes of tox4. I then proceeeded to generate the manpage using a) a tiny modifications to docs/conf.py, b) a docs/man.rst template with the header, synopsis etc. You can find the patch here: https://salsa.debian.org/python-team/packages/tox/-/blob/debian/latest/debian/patches/sphinx-manpage-conf.patch The output is not the prettiest thing in the world, but it's better than no manpage at all, and better than handcrafting the whole thing in roff :) Let me know what you think! |
The generated manpage is the entirety of tox's documentation. It's currently at ~6000 lines of groff text, including the entire changelog. We are currently shipping it in Debian, but it's clearly not great or super useful. We are also missing a man page for tox-quickstart.
argparse's default config (under
src/tox/config/__init__.py
) has a custom HelpFormatter that sets the line width to 190(!), and this then gets included to the manpage via the autoprogram Sphinx plugin. I don't really understand why the line width is non-standard (and excessive IMHO) andgit blame
wasn't super helpful either. argparse's description is also a non-description ("tox options"), so that wasn't great either.I've experimented a little bit with removing the HelpFormatter entirely and generating a manpage just with the output of
autoprogram
; this looks much better already, but the pendulum swinged too much the other way now - no section, or a proper description. My second experiment was creating this:Unfortunately, I haven't found a way to manipulate autoprogram's output to:
My third experiment was to try out
sphinx-argparse
and its (undocumented):manpage:
option; that was buggy (alex-rudakov/sphinx-argparse#82), so I ultimately failed there as well.My Sphinx foo isn't strong, so perhaps another member of the community could help get this completed :) Thanks!
The text was updated successfully, but these errors were encountered: