docs: Integrate sphinx-issues into the Sphinx config (#12616)

By using sphinx-issues, we can use consistent roles for common links.

NEWS.rst

@@ -3350,7 +3350,7 @@ Improved Documentation
 - Upgrade the bundled copy of requests to 2.6.0, fixing CVE-2015-2296.
 - Display format of latest package when using ``pip list --outdated``. (#2475)
 - Don't use pywin32 as ctypes should always be available on Windows, using
-  pywin32 prevented uninstallation of pywin32 on Windows. (:pull:`2467`)
+  pywin32 prevented uninstallation of pywin32 on Windows. (:pr:`2467`)
 - Normalize the ``--wheel-dir`` option, expanding out constructs such as ``~``
   when used. (#2441)
 - Display a warning when an undefined extra has been requested. (#2142)
@@ -3641,7 +3641,7 @@ Improved Documentation
   --no-download`` are now formally deprecated.  See #906 for discussion on
   possible alternatives, or lack thereof, in future releases.
 - **DEPRECATION** ``pip zip`` and ``pip unzip`` are now formally deprecated.
-- pip will now install Mac OSX platform wheels from PyPI. (:pull:`1278`)
+- pip will now install Mac OSX platform wheels from PyPI. (:pr:`1278`)
 - pip now generates the appropriate platform-specific console scripts when
   installing wheels. (#1251)
 - pip now confirms a wheel is supported when installing directly from a path or

docs/html/conf.py

@@ -17,7 +17,6 @@
     # first-party extensions
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
-    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     # our extensions
     "pip_sphinxext",
@@ -26,6 +25,7 @@
     "sphinx_copybutton",
     "sphinx_inline_tabs",
     "sphinxcontrib.towncrier",
+    "sphinx_issues",
 ]
 
 # General information about the project.
@@ -71,14 +71,6 @@
     "pypug": ("https://packaging.python.org", None),
 }
 
-# -- Options for extlinks -------------------------------------------------------------
-
-extlinks = {
-    "issue": ("https://github.com/pypa/pip/issues/%s", "#%s"),
-    "pull": ("https://github.com/pypa/pip/pull/%s", "PR #%s"),
-    "pypi": ("https://pypi.org/project/%s/", "%s"),
-}
-
 # -- Options for towncrier_draft extension --------------------------------------------
 
 towncrier_draft_autoversion_mode = "draft"  # or: 'sphinx-release', 'sphinx-version'
@@ -137,3 +129,7 @@ def to_document_name(path: str, base_dir: str) -> str:
 copybutton_prompt_text = r"\$ | C\:\> "
 copybutton_prompt_is_regexp = True
 copybutton_only_copy_prompt_lines = False
+
+# -- Options for sphinx_issues --------------------------------------------------------
+
+issues_default_group_project = "pypa/pip"

docs/requirements.txt

@@ -7,6 +7,7 @@ myst_parser
 sphinx-copybutton
 sphinx-inline-tabs
 sphinxcontrib-towncrier >= 0.2.0a0
+sphinx-issues
 
 # `docs.pipext` uses pip's internals to generate documentation. So, we install
 # the current directory to make it work.

news/12551.trivial.rst

@@ -0,0 +1 @@
+Integrate ``sphinx-issues`` into the Sphinx config.