Docs: add link roles with Sphinx extlinks (#117850)

Co-authored-by: Alex Waygood <[email protected]>

Author: hugovk

Doc/conf.py

@@ -12,6 +12,8 @@
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
+from pyspecific import SOURCE_URI
+
 # General configuration
 # ---------------------
 
@@ -24,6 +26,7 @@
     'pyspecific',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
+    'sphinx.ext.extlinks',
 ]
 
 # Skip if downstream redistributors haven't installed them
@@ -513,6 +516,19 @@
     r'https://unix.org/version2/whatsnew/lp64_wp.html',
 ]
 
+# Options for sphinx.ext.extlinks
+# -------------------------------
+
+# This config is a dictionary of external sites,
+# mapping unique short aliases to a base URL and a prefix.
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+extlinks = {
+    "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
+    "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
+    "pypi": ("https://pypi.org/project/%s/", "%s"),
+    "source": (SOURCE_URI, "%s"),
+}
+extlinks_detect_hardcoded_links = True
 
 # Options for extensions
 # ----------------------

Doc/faq/library.rst

@@ -616,16 +616,15 @@ use ``p.read(n)``.
    ("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
    "expect" library.  A Python extension that interfaces to expect is called
    "expy" and available from https://expectpy.sourceforge.net.  A pure Python
-   solution that works like expect is `pexpect
-   <https://pypi.org/project/pexpect/>`_.
+   solution that works like expect is :pypi:`pexpect`.
 
 
 How do I access the serial (RS232) port?
 ----------------------------------------
 
 For Win32, OSX, Linux, BSD, Jython, IronPython:
 
-   https://pypi.org/project/pyserial/
+   :pypi:`pyserial`
 
 For Unix, see a Usenet post by Mitch Chapman:
 

Doc/howto/curses.rst

@@ -43,7 +43,7 @@ appearance---and the curses library will figure out what control codes
 need to be sent to the terminal to produce the right output.  curses
 doesn't provide many user-interface concepts such as buttons, checkboxes,
 or dialogs; if you need such features, consider a user interface library such as
-`Urwid <https://pypi.org/project/urwid/>`_.
+:pypi:`Urwid`.
 
 The curses library was originally written for BSD Unix; the later System V
 versions of Unix from AT&T added many enhancements and new functions. BSD curses
@@ -56,8 +56,7 @@ versions of curses carried by some proprietary Unixes may not support
 everything, though.
 
 The Windows version of Python doesn't include the :mod:`curses`
-module.  A ported version called `UniCurses
-<https://pypi.org/project/UniCurses>`_ is available.
+module.  A ported version called :pypi:`UniCurses` is available.
 
 
 The Python curses module
@@ -429,8 +428,7 @@ User Input
 
 The C curses library offers only very simple input mechanisms. Python's
 :mod:`curses` module adds a basic text-input widget.  (Other libraries
-such as `Urwid <https://pypi.org/project/urwid/>`_ have more extensive
-collections of widgets.)
+such as :pypi:`Urwid` have more extensive collections of widgets.)
 
 There are two methods for getting input from a window:
 

Doc/howto/logging-cookbook.rst

@@ -1912,7 +1912,7 @@ Subclassing QueueHandler and QueueListener- a ``pynng`` example
 ---------------------------------------------------------------
 
 In a similar way to the above section, we can implement a listener and handler
-using `pynng <https://pypi.org/project/pynng/>`_, which is a Python binding to
+using :pypi:`pynng`, which is a Python binding to
 `NNG <https://nng.nanomsg.org/>`_, billed as a spiritual successor to ZeroMQ.
 The following snippets illustrate -- you can test them in an environment which has
 ``pynng`` installed. Just for variety, we present the listener first.
@@ -3575,9 +3575,8 @@ A Qt GUI for logging
 
 A question that comes up from time to time is about how to log to a GUI
 application. The `Qt <https://www.qt.io/>`_ framework is a popular
-cross-platform UI framework with Python bindings using `PySide2
-<https://pypi.org/project/PySide2/>`_ or `PyQt5
-<https://pypi.org/project/PyQt5/>`_ libraries.
+cross-platform UI framework with Python bindings using :pypi:`PySide2`
+or :pypi:`PyQt5` libraries.
 
 The following example shows how to log to a Qt GUI. This introduces a simple
 ``QtHandler`` class which takes a callable, which should be a slot in the main

Doc/library/codecs.rst

@@ -1478,7 +1478,7 @@ Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
 and :mod:`stringprep`.
 
 If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the
-third-party `idna module <https://pypi.org/project/idna/>`_.
+third-party :pypi:`idna` module.
 
 These RFCs together define a protocol to support non-ASCII characters in domain
 names. A domain name containing non-ASCII characters (such as

Doc/library/datetime.rst

@@ -37,7 +37,7 @@ on efficient attribute extraction for output formatting and manipulation.
    Package `dateutil <https://dateutil.readthedocs.io/en/stable/>`_
       Third-party library with expanded time zone and parsing support.
 
-   Package `DateType <https://pypi.org/project/datetype/>`_
+   Package :pypi:`DateType`
       Third-party library that introduces distinct static types to e.g. allow
       :term:`static type checkers <static type checker>`
       to differentiate between naive and aware datetimes.

Doc/library/importlib.metadata.rst

@@ -26,7 +26,7 @@ this package can eliminate the need to use the older and less efficient
 
 ``importlib.metadata`` operates on third-party *distribution packages*
 installed into Python's ``site-packages`` directory via tools such as
-`pip <https://pypi.org/project/pip/>`_.
+:pypi:`pip`.
 Specifically, it works with distributions with discoverable
 ``dist-info`` or ``egg-info`` directories,
 and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.
@@ -177,7 +177,7 @@ for more information on entry points, their definition, and usage.
    no parameters and always returned a dictionary of entry points, keyed
    by group. With ``importlib_metadata`` 5.0 and Python 3.12,
    ``entry_points`` always returns an ``EntryPoints`` object. See
-   `backports.entry_points_selectable <https://pypi.org/project/backports.entry-points-selectable>`_
+   :pypi:`backports.entry_points_selectable`
    for compatibility options.
 
 .. versionchanged:: 3.13

Doc/library/itertools.rst

@@ -791,7 +791,7 @@ recipes.  Currently, the ``sliding_window()``, ``iter_index()``, and ``sieve()``
 recipes are being tested to see whether they prove their worth.
 
 Substantially all of these recipes and many, many others can be installed from
-the `more-itertools project <https://pypi.org/project/more-itertools/>`_ found
+the :pypi:`more-itertools` project found
 on the Python Package Index::
 
     python -m pip install more-itertools

Doc/library/re.rst

@@ -48,7 +48,7 @@ fine-tuning parameters.
 
 .. seealso::
 
-   The third-party `regex <https://pypi.org/project/regex/>`_ module,
+   The third-party :pypi:`regex` module,
    which has an API compatible with the standard library :mod:`re` module,
    but offers additional functionality and a more thorough Unicode support.
 

Doc/library/secrets.rst

@@ -155,7 +155,7 @@ Generate an eight-character alphanumeric password:
 .. note::
 
    Applications should not
-   `store passwords in a recoverable format <https://cwe.mitre.org/data/definitions/257.html>`_,
+   :cwe:`store passwords in a recoverable format <257>`,
    whether plain text or encrypted.  They should be salted and hashed
    using a cryptographically strong one-way (irreversible) hash function.