From 782c3a26f623dc406b795e4c62285150495c46b6 Mon Sep 17 00:00:00 2001
From: Matthew Hughes <matthewhughes934@gmail.com>
Date: Wed, 15 Jan 2025 18:58:05 +0000
Subject: [PATCH] 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: https://github.com/pypa/pip/pull/12900 [1]
Link: https://github.com/pypa/pip/issues/12881 [2]
---
 docs/html/conf.py  | 32 ++++++++++++++++++++------------
 news/13168.doc.rst |  3 +++
 noxfile.py         |  2 ++
 3 files changed, 25 insertions(+), 12 deletions(-)
 create mode 100644 news/13168.doc.rst

diff --git a/docs/html/conf.py b/docs/html/conf.py
index be95eca2941..a31396bc13c 100644
--- a/docs/html/conf.py
+++ b/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"
diff --git a/news/13168.doc.rst b/news/13168.doc.rst
new file mode 100644
index 00000000000..7681e00fcdb
--- /dev/null
+++ b/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.
diff --git a/noxfile.py b/noxfile.py
index 70e24a01142..1df695ea3b7 100644
--- a/noxfile.py
+++ b/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,