Consider using a separate conf.py for sphinx manpages

eli-schwartz commented 1 month ago

What's the problem this feature will solve?

I would like to include roff manpages when installing pip via a linux distro package manager.

Currently I can do that via:

sphinx-build \
    -c docs/html \
    -d docs/build/doctrees/man \
    -b man \
    docs/man \
    docs/build/man

To do that, I need to install myst_parser, sphinx_copybutton, sphinx_inline_tabs, and sphinxcontrib.towncrier. And the last one currently isn't packaged at all, so I would have to add this package first, even though it appears to only be used by the HTML documentation.

Describe the solution you'd like

Add a docs/man/conf.py containing a bit of common config (version extraction, loading pip_sphinxext) and the "Options for Manual Pages" section.

Alternative Solutions

Manually create the roff manpages and upload them at release time as a github releases asset?

Additional context

n/a

Code of Conduct

[X] I agree to follow the PSF Code of Conduct.

ichard26 commented 1 month ago

A PR would be welcome. I don't think anyone on the core team uses pip's man pages (I forgot that they existed!) or has any particular expertise on them, so this wouldn't be high priority.

matthewhughes934 commented 1 month ago

A PR would be welcome. I don't think anyone on the core team uses pip's man pages (I forgot that they existed!) or has any particular expertise on them, so this wouldn't be high priority.

I got curious, so I gave this a shot with https://github.com/pypa/pip/pull/12900

eli-schwartz commented 2 weeks ago

@matthewhughes934 thanks for looking into this! <3

I tried it out and it seems to work very well. Looking forward to having it merged and available for me to use.

pypa / pip