Consider using a separate conf.py for sphinx manpages #12881
Labels
help wanted
For requesting inputs from other members of the community
type: docs
Documentation related
Comments
eli-schwartz
added
S: needs triage
ichard26
added
type: docs
|
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
added a commit
to matthewhughes934/pip
that referenced
this issue
Aug 6, 2024
The goal here is to allow building the `man` pages without all the
additional requirements needed for the `html` docs, so that e.g.
developers packaging `pip` can also package the man pages with minimal
dependencies.
Specifically, this should have no impact on the build output of `nox -s
docs`, but does allow:
sphinx-build \
-c docs/man \
-d docs/build/doctrees/man \
-b man \
docs/man \
docs/build/man
to run with only `sphinx` dependency (in addition to `pip`s
dependencies). While doing this I also used long-opts to `sphinx-build`
in the `noxfile` since I found this more understandable at a glance
Exceptions for `docs/{man,html}` was added for the `mypy` `pre-commit`
hook, since otherwise it errors:
docs/man/conf.py: error: Duplicate module named "conf" (also at
"docs/html/conf.py")
docs/man/conf.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
docs/man/conf.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
Found 1 error in 1 file (errors prevented further checking)
and the alternative of adding `__init__.py` means that under `docs` the
`html` module is local (and not the stdlib one) resulting in a error
from `sphinx-build`:
Extension error:
Could not import extension sphinx.builders.linkcheck (exception: No module named 'html.parser')
Issue: pypa#12881
I got curious, so I gave this a shot with #12900 |
matthewhughes934
added a commit
to matthewhughes934/pip
that referenced
this issue
Aug 15, 2024
The goal here is to allow building the `man` pages without all the
additional requirements needed for the `html` docs, so that e.g.
developers packaging `pip` can also package the man pages with minimal
dependencies.
Specifically, this should have no impact on the build output of `nox -s
docs`, but does allow:
sphinx-build \
-c docs/man \
-d docs/build/doctrees/man \
-b man \
docs/man \
docs/build/man
to run with only `sphinx` dependency (in addition to `pip`s
dependencies). While doing this I also used long-opts to `sphinx-build`
in the `noxfile` since I found this more understandable at a glance
An `__init__.py` was added under `docs/man` to satisfy `mypy`. If this
wasn't added it would error:
docs/man/conf.py: error: Duplicate module named "conf" (also at
"docs/html/conf.py")
docs/man/conf.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
docs/man/conf.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
Found 1 error in 1 file (errors prevented further checking)
Adding an extra `__init__.py` under `docs/html` would result in a
separate error since then the `html` module is local (and not the stdlib
one) resulting in a error from `sphinx-build`:
Extension error:
Could not import extension sphinx.builders.linkcheck (exception: No module named 'html.parser')
Issue: pypa#12881
Avoid mypy ignore for docs by just adding one `__init__.py`
matthewhughes934
added a commit
to matthewhughes934/pip
that referenced
this issue
Aug 15, 2024
The goal here is to allow building the `man` pages without all the
additional requirements needed for the `html` docs, so that e.g.
developers packaging `pip` can also package the man pages with minimal
dependencies.
Specifically, this should have no impact on the build output of `nox -s
docs`, but does allow:
sphinx-build \
-c docs/man \
-d docs/build/doctrees/man \
-b man \
docs/man \
docs/build/man
to run with only `sphinx` dependency (in addition to `pip`s
dependencies). While doing this I also used long-opts to `sphinx-build`
in the `noxfile` since I found this more understandable at a glance
An `__init__.py` was added under `docs/man` to satisfy `mypy`. If this
wasn't added it would error:
docs/man/conf.py: error: Duplicate module named "conf" (also at
"docs/html/conf.py")
docs/man/conf.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
docs/man/conf.py: note: Common resolutions include: a) using `--exclude` to avoid checking one of them, b) adding `__init__.py` somewhere, c) using `--explicit-package-bases` or adjusting MYPYPATH
Found 1 error in 1 file (errors prevented further checking)
Adding an extra `__init__.py` under `docs/html` would result in a
separate error since then the `html` module is local (and not the stdlib
one) resulting in a error from `sphinx-build`:
Extension error:
Could not import extension sphinx.builders.linkcheck (exception: No module named 'html.parser')
Issue: pypa#12881
|
@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. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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:
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
The text was updated successfully, but these errors were encountered: