Skip to content
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

Open
paravoid opened this issue Aug 28, 2019 · 3 comments
Open

Ship a better/proper manpage #1409

paravoid opened this issue Aug 28, 2019 · 3 comments
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.

Comments

@paravoid
Copy link
Contributor

paravoid commented Aug 28, 2019

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!

@paravoid paravoid added the bug:normal affects many people or has quite an impact label Aug 28, 2019
@paravoid
Copy link
Contributor Author

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
Copy link
Member

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

@gaborbernat gaborbernat added this to the 4.1 milestone Jan 13, 2022
@paravoid
Copy link
Contributor Author

paravoid commented Feb 14, 2023

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!

@gaborbernat gaborbernat added the help:wanted Issues that have been acknowledged, a solution determined and a PR might likely be accepted. label Jun 16, 2023
@gaborbernat gaborbernat removed this from the P-1 milestone Jun 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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.
Projects
None yet
Development

No branches or pull requests

2 participants