10000 [3.12] Docs: add link roles with Sphinx extlinks (GH-117850) (#117910) · python/cpython@eb0bfb5 · GitHub
[go: up one dir, main page]
Skip to content

Commit eb0bfb5

Browse files
hugovkAlexWaygood
hugovk
and
AlexWaygood
authored
[3.12] Docs: add link roles with Sphinx extlinks (GH-117850) (#117910)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent 6dfb7e1 commit eb0bfb5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+134
-161
lines changed

‎Doc/c-api/init.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -760,7 +760,7 @@ Process-wide parameters
760760
It is recommended that applications embedding the Python interpreter
761761
for purposes other than executing a single script pass ``0`` as *updatepath*,
762762
and update :data:`sys.path` themselves if desired.
763-
See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
763+
See :cve:`2008-5983`.
764764

765765
On versions before 3.1.3, you can achieve the same effect by manually
766766
popping the first :data:`sys.path` element after having called

‎Doc/conf.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
sys.path.append(os.path.abspath('tools/extensions'))
1313
sys.path.append(os.path.abspath('includes'))
1414

15+
from pyspecific import SOURCE_URI
16+
1517
# General configuration
1618
# ---------------------
1719

@@ -24,6 +26,7 @@
2426
'pyspecific',
2527
'sphinx.ext.coverage',
2628
'sphinx.ext.doctest',
29+
'sphinx.ext.extlinks',
2730
]
2831

2932
# Skip if downstream redistributors haven't installed it
@@ -499,6 +502,19 @@
499502
r'https://unix.org/version2/whatsnew/lp64_wp.html',
500503
]
501504

505+
# Options for sphinx.ext.extlinks
506+
# -------------------------------
507+
508+
# This config is a dictionary of external sites,
509+
# mapping unique short aliases to a base URL and a prefix.
510+
# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
511+
extlinks = {
512+
"cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
513+
"cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
514+
"pypi": ("https://pypi.org/project/%s/", "%s"),
515+
"source": (SOURCE_URI, "%s"),
516+
}
517+
extlinks_detect_hardcoded_links = True
502518

503519
# Options for extensions
504520
# ----------------------

‎Doc/faq/library.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -610,16 +610,15 @@ use ``p.read(n)``.
610610
("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
611611
"expect" library. A Python extension that interfaces to expect is called
612612
"expy" and available from https://expectpy.sourceforge.net. A pure Python
613-
solution that works like expect is `pexpect
614-
<https://pypi.org/project/pexpect/>`_.
613+
solution that works like expect is :pypi:`pexpect`.
615614
616615
617616
How do I access the serial (RS232) port?
618617
----------------------------------------
619618
620619
For Win32, OSX, Linux, BSD, Jython, IronPython:
621620
622-
https://pypi.org/project/pyserial/
621+
:pypi:`pyserial`
623622
624623
For Unix, see a Usenet post by Mitch Chapman:
625624

‎Doc/howto/curses.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ appearance---and the curses library will figure out what control codes
4343
need to be sent to the terminal to produce the right output. curses
4444
doesn't provide many user-interface concepts such as buttons, checkboxes,
4545
or dialogs; if you need such features, consider a user interface library such as
46-
`Urwid <https://pypi.org/project/urwid/>`_.
46+
:pypi:`Urwid`.
4747

4848
The curses library was originally written for BSD Unix; the later System V
4949
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
5656
everything, though.
5757

5858
The Windows version of Python doesn't include the :mod:`curses`
59-
module. A ported version called `UniCurses
60-
<https://pypi.org/project/UniCurses>`_ is available.
59+
module. A ported version called :pypi:`UniCurses` is available.
6160

6261

6362
The Python curses module
@@ -429,8 +428,7 @@ User Input
429428

430429
The C curses library offers only very simple input mechanisms. Python's
431430
:mod:`curses` module adds a basic text-input widget. (Other libraries
432-
such as `Urwid <https://pypi.org/project/urwid/>`_ have more extensive
433-
collections of widgets.)
431+
such as :pypi:`Urwid` have more extensive collections of widgets.)
434432

435433
There are two methods for getting input from a window:
436434

‎Doc/howto/logging-cookbook.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1912,7 +1912,7 @@ Subclassing QueueHandler and QueueListener- a ``pynng`` example
19121912
---------------------------------------------------------------
19131913

19141914
In a similar way to the above section, we can implement a listener and handler
1915-
using `pynng <https://pypi.org/project/pynng/>`_, which is a Python binding to
1915+
using :pypi:`pynng`, which is a Python binding to
19161916
`NNG <https://nng.nanomsg.org/>`_, billed as a spiritual successor to ZeroMQ.
19171917
The following snippets illustrate -- you can test them in an environment which has
19181918
``pynng`` installed. Just for variety, we present the listener first.
@@ -3575,9 +3575,8 @@ A Qt GUI for logging
35753575

35763576
A question that comes up from time to time is about how to log to a GUI
35773577
application. The `Qt <https://www.qt.io/>`_ framework is a popular
3578-
cross-platform UI framework with Python bindings using `PySide2
3579-
<https://pypi.org/project/PySide2/>`_ or `PyQt5
3580-
<https://pypi.org/project/PyQt5/>`_ libraries.
3578+
cross-platform UI framework with Python bindings using :pypi:`PySide2`
3579+
or :pypi:`PyQt5` libraries.
35813580

35823581
The following example shows how to log to a Qt GUI. This introduces a simple
35833582
``QtHandler`` class which takes a callable, which should be a slot in the main

‎Doc/library/cgi.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
The :class:`FieldStorage` class can typically be replaced with
2323
:func:`urllib.parse.parse_qsl` for ``GET`` and ``HEAD`` requests,
2424
and the :mod:`email.message` module or
25-
`multipart <https://pypi.org/project/multipart/>`_ for ``POST`` and ``PUT``.
25+
:pypi:`multipart` for ``POST`` and ``PUT``.
2626
Most :ref:`utility functions <functions-in-cgi-module>` have replacements.
2727

2828
--------------
@@ -334,7 +334,7 @@ algorithms implemented in this module in other circumstances.
334334
It can be replaced with the functionality in the :mod:`email` package
335335
(e.g. :class:`email.message.EmailMessage`/:class:`email.message.Message`)
336336
which implements the same MIME RFCs, or with the
337-
`multipart <https://pypi.org/project/multipart/>`__ PyPI project.
337+
:pypi:`multipart` PyPI project.
338338

339339

340340
.. function:: parse_header(string)

‎Doc/library/codecs.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1479,7 +1479,7 @@ Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
14791479
and :mod:`stringprep`.
14801480

14811481
If you need the IDNA 2008 standard from :rfc:`5891` and :rfc:`5895`, use the
1482-
third-party `idna module <https://pypi.org/project/idna/>`_.
1482+
third-party :pypi:`idna` module.
14831483

14841484
These RFCs together define a protocol to support non-ASCII characters in domain
14851485
names. A domain name containing non-ASCII characters (such as

‎Doc/library/crypt.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
The :mod:`crypt` module is deprecated
2121
(see :pep:`PEP 594 <594#crypt>` for details and alternatives).
2222
The :mod:`hashlib` module is a potential replacement for certain use cases.
23-
The `passlib <https://pypi.org/project/passlib/>`_ package can replace all use cases of this module.
23+
The :pypi:`passlib` package can replace all use cases of this module.
2424

2525
--------------
2626

‎Doc/library/datetime.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ on efficient attribute extraction for output formatting and manipulation.
3737
Package `dateutil <https://dateutil.readthedocs.io/en/stable/>`_
3838
Third-party library with expanded time zone and parsing support.
3939

40-
Package `DateType <https://pypi.org/project/datetype/>`_
40+
Package :pypi:`DateType`
4141
Third-party library that introduces distinct static types to e.g. allow
4242
:term:`static type checkers <static type checker>`
4343
to differentiate between naive and aware datetimes.

‎Doc/library/importlib.metadata.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ this package can eliminate the need to use the older and less efficient
2626

2727
``importlib.metadata`` operates on third-party *distribution packages*
2828
installed into Python's ``site-packages`` directory via tools such as
29-
`pip <https://pypi.org/project/pip/>`_.
29+
:pypi:`pip`.
3030
Specifically, it works with distributions with discoverable
3131
``dist-info`` or ``egg-info`` directories,
3232
and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.
@@ -178,7 +178,7 @@ The "selectable" entry points were introduced in ``importlib_metadata``
178178
no parameters and always returned a dictionary of entry points, keyed
179179
by group. With ``importlib_metadata`` 5.0 and Python 3.12,
180180
``entry_points`` always returns an ``EntryPoints`` object. See
181-
`backports.entry_points_selectable <https://pypi.org/project/backports.entry-points-selectable>`_
181+
:pypi:`backports.entry_points_selectable`
182182
for compatibility options.
183183

184184

‎Doc/library/itertools.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -783,7 +783,7 @@ recipes. Currently, the ``sliding_window()``, ``iter_index()``, and ``sieve()``
783783
recipes are being tested to see whether they prove their worth.
784784

785785
Substantially all of these recipes and many, many others can be installed from
786-
the `more-itertools project <https://pypi.org/project/more-itertools/>`_ found
786+
the :pypi:`more-itertools` project found
787787
on the Python Package Index::
788788

789789
python -m pip install more-itertools

‎Doc/library/re.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ fine-tuning parameters.
4848

4949
.. seealso::
5050

51-
The third-party `regex <https://pypi.org/project/regex/>`_ module,
51+
The third-party :pypi:`regex` module,
5252
which has an API compatible with the standard library :mod:`re` module,
5353
but offers additional functionality and a more thorough Unicode support.
5454

‎Doc/library/secrets.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ Generate an eight-character alphanumeric password:
155155
.. note::
156156

157157
Applications should not
158-
`store passwords in a recoverable format <https://cwe.mitre.org/data/definitions/257.html>`_,
158+
:cwe:`store passwords in a recoverable f F438 ormat <257>`,
159159
whether plain text or encrypted. They should be salted and hashed
160160
using a cryptographically strong one-way (irreversible) hash function.
161161

‎Doc/library/stdtypes.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5550,8 +5550,7 @@ a string to a binary integer or a binary integer to a string in linear time,
55505550
have sub-quadratic complexity. Converting a large value such as ``int('1' *
55515551
500_000)`` can take over a second on a fast CPU.
55525552

5553-
Limiting conversion size offers a practical way to avoid `CVE-2020-10735
5554-
<https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735>`_.
5553+
Limiting conversion size offers a practical way to avoid :cve:`2020-10735`.
55555554

55565555
The limit is applied to the number of digit characters in the input or output
55575556
string when a non-linear conversion algorithm would be involved. Underscores

‎Doc/library/tomllib.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@ support writing TOML.
1919

2020
.. seealso::
2121

22-
The `Tomli-W package <https://pypi.org/project/tomli-w/>`__
22+
The :pypi:`Tomli-W package <tomli-w>`
2323
is a TOML writer that can be used in conjunction with this module,
2424
providing a write API familiar to users of the standard library
2525
:mod:`marshal` and :mod:`pickle` modules.
2626

2727
.. seealso::
2828

29-
The `TOML Kit package <https://pypi.org/project/tomlkit/>`__
29+
The :pypi:`TOML Kit package <tomlkit>`
3030
is a style-preserving TOML library with both read and write capability.
3131
It is a recommended replacement for this module for editing already
3232
existing TOML files.

‎Doc/library/typing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ they can also be more complex. The :mod:`typing` module provides a vocabulary of
3939
more advanced type hints.
4040

4141
New features are frequently added to the ``typing`` module.
42-
The `typing_extensions <https://pypi.org/project/typing-extensions/>`_ package
42+
The :pypi:`typing_extensions` package
4343
provides backports of these new features to older versions of Python.
4444

4545
.. seealso::

‎Doc/library/unittest.mock.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ is based on the 'action -> assertion' pattern instead of 'record -> replay'
3535
used by many mocking frameworks.
3636

3737
There is a backport of :mod:`unittest.mock` for earlier versions of Python,
38-
available as `mock on PyPI <https://pypi.org/project/mock>`_.
38+
available as :pypi:`mock` on PyPI.
3939

4040

4141
Quick Guide

‎Doc/library/venv.rst

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ optionally be isolated from the packages in the base environment,
2727
so only those explicitly installed in the virtual environment are available.
2828

2929
When used from within a virtual environment, common installation tools such as
30-
`pip`_ will install Python packages into a virtual environment
30+
:pypi:`pip` will install Python packages into a virtual environment
3131
without needing to be told to do so explicitly.
3232

3333
A virtual environment is (amongst other things):
@@ -594,7 +594,3 @@ subclass which installs setuptools and pip into a created virtual environment::
594594

595595
This script is also available for download `online
596596
<https://gist.github.com/vsajip/4673395>`_.
597-
598-
599-
.. _setuptools: https://pypi.org/project/setuptools/
600-
.. _pip: https://pypi.org/project/pip/

‎Doc/library/xml.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -124,25 +124,23 @@ large tokens
124124
Expat needs to re-parse unfinished tokens; without the protection
125125
introduced in Expat 2.6.0, this can lead to quadratic runtime that can
126126
be used to cause denial of service in the application parsing XML.
127-
The issue is known as
128-
`CVE-2023-52425 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-52425>`_.
127+
The issue is known as :cve:`2023-52425`.
129128

130-
The documentation for `defusedxml`_ on PyPI has further information about
129+
The documentation for :pypi:`defusedxml` on PyPI has further information about
131130
all known attack vectors with examples and references.
132131

133132
.. _defusedxml-package:
134133

135134
The :mod:`!defusedxml` Package
136135
------------------------------
137136

138-
`defusedxml`_ is a pure Python package with modified subclasses of all stdlib
137+
:pypi:`defusedxml` is a pure Python package with modified subclasses of all stdlib
139138
XML parsers that prevent any potentially malicious operation. Use of this
140139
package is recommended for any server code that parses untrusted XML data. The
141140
package also ships with example exploits and extended documentation on more
142141
XML exploits such as XPath injection.
143142

144143

145-
.. _defusedxml: https://pypi.org/project/defusedxml/
146144
.. _Billion Laughs: https://en.wikipedia.org/wiki/Billion_laughs
147145
.. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb
148146
.. _DTD: https://en.wikipedia.org/wiki/Document_type_definition

‎Doc/library/zipfile.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@ Path objects are traversable using the ``/`` operator or ``joinpath``.
626626
Prior to 3.10, ``joinpath`` was undocumented and accepted
627627
exactly one parameter.
628628

629-
The `zipp <https://pypi.org/project/zipp>`_ project provides backports
629+
The :pypi:`zipp` project provides backports
630630
of the latest path object functionality to older Pythons. Use
631631
``zipp.Path`` in place of ``zipfile.Path`` for early access to
632632
changes.

‎Doc/library/zoneinfo.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,15 @@ The :mod:`zoneinfo` module provides a concrete time zone implementation to
1717
support the IANA time zone database as originally specified in :pep:`615`. By
1818
default, :mod:`zoneinfo` uses the system's time zone data if available; if no
1919
system time zone data is available, the library will fall back to using the
20-
first-party `tzdata`_ package available on PyPI.
20+
first-party :pypi:`tzdata` package available on PyPI.
2121

2222
.. seealso::
2323

2424
Module: :mod:`datetime`
2525
Provides the :class:`~datetime.time` and :class:`~datetime.datetime`
2626
types with which the :class:`ZoneInfo` class is designed to be used.
2727

28-
Package `tzdata`_
28+
Package :pypi:`tzdata`
2929
First-party package maintained by the CPython core developers to supply
3030
time zone data via PyPI.
3131

@@ -93,7 +93,7 @@ Data sources
9393

9494
The ``zoneinfo`` module does not directly provide time zone data, and instead
9595
pulls time zone information from the system time zone database or the
96-
first-party PyPI package `tzdata`_, if available. Some systems, including
96+
first-party PyPI package :pypi:`tzdata`, if available. Some systems, including
9797
notably Windows systems, do not have an IANA database available, and so for
9898
projects targeting cross-platform compatibility that require time zone data, it
9999
is recommended to declare a dependency on tzdata. If neither system data nor
@@ -413,5 +413,3 @@ Exceptions and warnings
413413
be filtered out, such as a relative path.
414414

415415
.. Links and references:
416-
417-
.. _tzdata: https://pypi.org/project/tzdata/

‎Doc/tools/extensions/pyspecific.py

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@
2626
from sphinx.locale import _ as sphinx_gettext
2727
from sphinx.util import logging
2828
from sphinx.util.docutils import SphinxDirective
29-
from sphinx.util.nodes import split_explicit_title
3029
from sphinx.writers.text import TextWriter, TextTranslator
3130

3231
try:
@@ -39,6 +38,7 @@
3938

4039
ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'
4140
GH_ISSUE_URI = 'https://github.com/python/cpython/issues/%s'
41+
# Used in conf.py and updated here by python/release-tools/run_release.py
4242
SOURCE_URI = 'https://github.com/python/cpython/tree/3.12/%s'
4343

4444
# monkey-patch reST parser to disable alphabetic and roman enumerated lists
@@ -54,6 +54,7 @@
5454

5555
std.token_re = re.compile(r'`((~?[\w-]*:)?\w+)`')
5656

57+
5758
# Support for marking up and linking to bugs.python.org issues
5859

5960
def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
@@ -85,16 +86,6 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
8586
return [refnode], []
8687

8788

88-
# Support for linking to Python source files easily
89-
90-
def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
91-
has_t, title, target = split_explicit_title(text)
92-
title = utils.unescape(title)
93-
target = utils.unescape(target)
94-
refnode = nodes.reference(title, title, refuri=SOURCE_URI % target)
95-
return [refnode], []
96-
97-
9889
# Support for marking up implementation details
99 57AE 90

10091
class ImplementationDetail(Directive):
@@ -194,7 +185,6 @@ def parse_platforms(self):
194185
return platforms
195186

196187

197-
198188
# Support for documenting audit event
199189

200190
def audit_events_purge(app, env, docname):
@@ -710,7 +700,6 @@ def patch_pairindextypes(app, _env) -> None:
710700
def setup(app):
711701
app.add_role('issue', issue_role)
712702
app.add_role('gh', gh_issue_role)
713-
app.add_role('source', source_role)
714703
app.add_directive('impl-detail', ImplementationDetail)
715704
app.add_directive('availability', Availability)
716705
app.add_directive('audit-event', AuditEvent)

0 commit comments

Comments
 (0)
0