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: pypa#12900 [1]
Link: pypa#12881 [2]

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.extlinks",
-    "sphinx.ext.intersphinx",
-    # our extensions
+    # extensions common to 'man' and 'html' builds
     "pip_sphinxext",
-    # third-party extensions
-    "myst_parser",
-    "sphinx_copybutton",
-    "sphinx_inline_tabs",
-    "sphinxcontrib.towncrier",
 ]
 
+# 'tags' is a special object handled by sphinx
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-tags
+if "html" in tags:  # type: ignore[name-defined] # noqa: F821
+    # html specific deps
+    extensions.extend(
+        (
+            # first-party extensions
+            "sphinx.ext.autodoc",
+            "sphinx.ext.todo",
+            "sphinx.ext.extlinks",
+            "sphinx.ext.intersphinx",
+            # third-party extensions
+            "myst_parser",
+            "sphinx_copybutton",
+            "sphinx_inline_tabs",
+            "sphinxcontrib.towncrier",
+        ),
+    )
+
 # General information about the project.
 project = "pip"
 copyright = "The pip developers"

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,