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.

Sign up for GitHub

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

Jump to bottom

Consider using a separate conf.py for sphinx manpages #12881

Open
1 task done
eli-schwartz opened this issue Jul 29, 2024 · 3 comments
Open
1 task done

Consider using a separate conf.py for sphinx manpages #12881

eli-schwartz opened this issue Jul 29, 2024 · 3 comments
Labels
help wanted For requesting inputs from other members of the community type: docs Documentation related

Comments

@eli-schwartz
Copy link
Contributor

eli-schwartz commented Jul 29, 2024 •
edited
Loading

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
@eli-schwartz eli-schwartz added S: needs triage Issues/PRs that need to be triaged type: feature request Request for a new feature labels Jul 29, 2024
@ichard26 ichard26 added type: docs Documentation related help wanted For requesting inputs from other members of the community and removed type: feature request Request for a new feature S: needs triage Issues/PRs that need to be triaged labels Jul 31, 2024
@ichard26
Copy link
Member

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
@matthewhughes934
Add separate conf.py for the different docs types
accf1cb 
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
@matthewhughes934 matthewhughes934 mentioned this issue Aug 6, 2024
Open
@matthewhughes934
Copy link
Contributor

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 #12900

matthewhughes934 added a commit to matthewhughes934/pip that referenced this issue Aug 15, 2024
@matthewhughes934
Add separate conf.py for the different docs types
e599386 
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
@matthewhughes934
Add separate conf.py for the different docs types
ac9e441 
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
@eli-schwartz
Copy link
Contributor Author

@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.

matthewhughes934 added a commit to matthewhughes934/pip that referenced this issue Oct 31, 2024
@matthewhughes934
Add separate conf.py for the different docs types
326638d 
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted For requesting inputs from other members of the community type: docs Documentation related
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@eli-schwartz @matthewhughes934 @ichard26