Ship a better/proper manpage

[paravoid]

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) and git 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:

tox
===

Name
----
*tox* - virtualenv-based automation of test activities

Synopsis
--------
**tox** [*options*] [*args* ...]

Description
-----------

.. should be split to a separate file
.. include:: index.rst
   :start-after:
     What is tox?
     --------------------
   :end-before:
     Basic example

Options
-------

.. autoprogram:: tox.cli:cli
   :prog: tox

See also
--------

:manpage:`tox-quickstart(1)`

.. include:: links.rst

Unfortunately, I haven't found a way to manipulate autoprogram's output to:

• remove the top-most "tox" section
• split the usage section from the options.

My third experiment was to try out sphinx-argparse and its (undocumented) :manpage: option; that was buggy (https://github.com/ribozz/sphinx-argparse/issues/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!

[paravoid]

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.

[gaborbernat]

I think with the looming tox 4 (#1400) we'll need to reconsider this.

[paravoid]

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!