Add separate conf.py for the different docs types

[matthewhughes934]

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 pips
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: #12881

[matthewhughes934]

Alternatively: add these to __all__ in docs/common_conf.py and import * from there, but I preferred being explicit

[uranusjr]

You can use __all__ to signify the values are re-exported.

[matthewhughes934]

You can use __all__ to signify the values are re-exported.

Are you suggesting add them to __all__ in this file, instead of the assignments below? Or add these to __all__ in common_conf and just import * here?

[ichard26]

Why not simply ignore the Ruff rule?

Suggested change

	from common_conf import copyright, project, release, version # noqa: E402
	from common_conf import copyright, project, release, version # noqa: E402, F401

---

Are you suggesting add them to __all__ in this file, instead of the assignments below?

Names declared in __all__ become part of the module's interface and thus Ruff won't delete unused imports that populate those names. AFAIU, this is what @uranusjr was suggesting. I think this is even less obvious to a reader.

Alternatively we could do from common_config import version as version for each configuration option to declare them as re-exports.

from common_conf import copyright as copyright  # noqa: E402
from common_conf import project as project  # noqa: E402
from common_conf import release as release  # noqa: E402
from common_conf import version as version  # noqa: E402

But this seems verbose IMO.

[matthewhughes934]

Why not simply ignore the Ruff rule?

No reason not to, see c04ff52

[ichard26]

You need to install the HTML dependencies in the docs-live nox session, otherwise it will break.

I don't like excluding the configuration files from mypy, but I also can't think of anything better...

[ichard26]

Why not simply ignore the Ruff rule?

Suggested change

	from common_conf import copyright, project, release, version # noqa: E402
	from common_conf import copyright, project, release, version # noqa: E402, F401

---

Are you suggesting add them to __all__ in this file, instead of the assignments below?

Names declared in __all__ become part of the module's interface and thus Ruff won't delete unused imports that populate those names. AFAIU, this is what @uranusjr was suggesting. I think this is even less obvious to a reader.

Alternatively we could do from common_config import version as version for each configuration option to declare them as re-exports.

from common_conf import copyright as copyright  # noqa: E402
from common_conf import project as project  # noqa: E402
from common_conf import release as release  # noqa: E402
from common_conf import version as version  # noqa: E402

But this seems verbose IMO.

[matthewhughes934]

You need to install the HTML dependencies in the docs-live nox session, otherwise it will break.

Thanks, I completely missed that one, fixed a08f157

[ichard26]

Actually, it looks like adding a __init__.py to only the man directory is a valid workaround.

[matthewhughes934]

Actually, it looks like adding a __init__.py to only the man directory is a valid workaround.

ah, good idea, trying this: 20cbe13

[ichard26]

Suggested change

# exclude due to errors from duplicate conf.py under docs

[matthewhughes934]

🤦 dab08d1

[sbidoul]

Sorry I have not had time to review nor test this. Postponing to 25.0.