Ship a better/proper manpage #1409
Labels
bug:normal
affects many people or has quite an impact
help:wanted
Issues that have been acknowledged, a solution determined and a PR might likely be accepted.
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: