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 (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!