Use tags in docs building to split up requirements

The goal is to allow a build of just the `man` pages with a minimal set
of dependencies, like:

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

This is for the sake of people distributing `pip` who want to build the
man pages (but not the HTML ones) along side the application.

This is an alternative to the approach proposed in[1] and similarly
addresses[2]

Link: #12900 [1]
Link: #12881 [2]

Author: matthewhughes934

docs/html/conf.py

@@ -12,22 +12,30 @@
 sys.path.insert(0, docs_dir)
 
 # -- General configuration ------------------------------------------------------------
-
 extensions = [
-    # first-party extensions
-    "sphinx.ext.autodoc",
-    "sphinx.ext.todo",
-    "sphinx.ext.intersphinx",
-    # our extensions
+    # extensions common to all builds
     "pip_sphinxext",
-    # third-party extensions
-    "myst_parser",
-    "sphinx_copybutton",
-    "sphinx_inline_tabs",
-    "sphinxcontrib.towncrier",
-    "sphinx_issues",
 ]
 
+# 'tags' is a injected by sphinx
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-tags
+if "man" not in tags:  # type: ignore[name-defined] # noqa: F821
+    # extensions not needed for building man pages
+    extensions.extend(
+        (
+            # first-party extensions
+            "sphinx.ext.autodoc",
+            "sphinx.ext.todo",
+            "sphinx.ext.intersphinx",
+            # third-party extensions
+            "myst_parser",
+            "sphinx_copybutton",
+            "sphinx_inline_tabs",
+            "sphinxcontrib.towncrier",
+            "sphinx_issues",
+        ),
+    )
+
 # General information about the project.
 project = "pip"
 copyright = "The pip developers"

news/13168.doc.rst

@@ -0,0 +1,3 @@
+Added support for building only the man pages with minimal dependencies using
+the sphinx-build ``--tag man`` option. This enables distributors to generate man
+pages without requiring HTML documentation dependencies.

noxfile.py

@@ -146,6 +146,8 @@ def get_sphinx_build_command(kind: str) -> List[str]:
         return [
             "sphinx-build",
             "--keep-going",
+            "--tag",
+            kind,
             "-W",
             "-c", "docs/html",  # see note above
             "-d", "docs/build/doctrees/" + kind,