Docs: use role to link to PEPs (#1568)

Author: hugovk

docs/index.rst

@@ -102,33 +102,33 @@ Typing PEPs
 
 https://peps.python.org/topic/typing
 
-* `PEP 482 <https://www.python.org/dev/peps/pep-0482/>`_, literature overview on type hints
-* `PEP 483 <https://www.python.org/dev/peps/pep-0483/>`_, background on type hints
-* `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_, type hints
-* `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_, variable annotations and ``ClassVar``
-* `PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_, ``Protocol``
-* `PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_, distributing typed packages
-* `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_, ``from __future__ import annotations``
-* `PEP 585 <https://www.python.org/dev/peps/pep-0585/>`_, subscriptable generics in the standard library
-* `PEP 586 <https://www.python.org/dev/peps/pep-0586/>`_, ``Literal``
-* `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_, ``TypedDict``
-* `PEP 591 <https://www.python.org/dev/peps/pep-0591/>`_, ``Final``
-* `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_, ``Annotated``
-* `PEP 604 <https://www.python.org/dev/peps/pep-0604/>`_, union syntax with ``|``
-* `PEP 612 <https://www.python.org/dev/peps/pep-0612/>`_, ``ParamSpec``
-* `PEP 613 <https://www.python.org/dev/peps/pep-0613/>`_, ``TypeAlias``
-* `PEP 646 <https://www.python.org/dev/peps/pep-0646/>`_, variadic generics and ``TypeVarTuple``
-* `PEP 647 <https://www.python.org/dev/peps/pep-0647/>`_, ``TypeGuard``
-* `PEP 649 <https://www.python.org/dev/peps/pep-0649/>`_ (draft), ``from __future__ import co_annotations``
-* `PEP 655 <https://www.python.org/dev/peps/pep-0655/>`_, ``Required`` and ``NotRequired``
-* `PEP 673 <https://www.python.org/dev/peps/pep-0673/>`_, ``Self``
-* `PEP 675 <https://www.python.org/dev/peps/pep-0675/>`_, ``LiteralString``
-* `PEP 677 <https://www.python.org/dev/peps/pep-0677/>`_ (rejected), ``(int, str) -> bool`` callable type syntax
-* `PEP 681 <https://www.python.org/dev/peps/pep-0681/>`_ ``@dataclass_transform()``
-* `PEP 688 <https://www.python.org/dev/peps/pep-0688/>`_ ``Buffer``
-* `PEP 692 <https://www.python.org/dev/peps/pep-0692/>`_ ``Unpack[TypedDict]`` for ``**kwargs``
-* `PEP 695 <https://www.python.org/dev/peps/pep-0695/>`_ ``class Class[T]:`` type parameter syntax
-* `PEP 696 <https://www.python.org/dev/peps/pep-0696/>`_ (draft), defaults for type variables
-* `PEP 698 <https://www.python.org/dev/peps/pep-0698/>`_ ``@override``
-* `PEP 702 <https://www.python.org/dev/peps/pep-0702/>`_ (draft), ``@deprecated()``
-* `PEP 705 <https://www.python.org/dev/peps/pep-0705/>`_ (draft), ``TypedMapping``
+* :pep:`482`, literature overview on type hints
+* :pep:`483`, background on type hints
+* :pep:`484`, type hints
+* :pep:`526`, variable annotations and ``ClassVar``
+* :pep:`544`, ``Protocol``
+* :pep:`561`, distributing typed packages
+* :pep:`563`, ``from __future__ import annotations``
+* :pep:`585`, subscriptable generics in the standard library
+* :pep:`586`, ``Literal``
+* :pep:`589`, ``TypedDict``
+* :pep:`591`, ``Final``
+* :pep:`593`, ``Annotated``
+* :pep:`604`, union syntax with ``|``
+* :pep:`612`, ``ParamSpec``
+* :pep:`613`, ``TypeAlias``
+* :pep:`646`, variadic generics and ``TypeVarTuple``
+* :pep:`647`, ``TypeGuard``
+* :pep:`649` (draft), ``from __future__ import co_annotations``
+* :pep:`655`, ``Required`` and ``NotRequired``
+* :pep:`673`, ``Self``
+* :pep:`675`, ``LiteralString``
+* :pep:`677` (rejected), ``(int, str) -> bool`` callable type syntax
+* :pep:`681` ``@dataclass_transform()``
+* :pep:`688` ``Buffer``
+* :pep:`692` ``Unpack[TypedDict]`` for ``**kwargs``
+* :pep:`695` ``class Class[T]:`` type parameter syntax
+* :pep:`696` (draft), defaults for type variables
+* :pep:`698` ``@override``
+* :pep:`702` (draft), ``@deprecated()``
+* :pep:`705` (draft), ``TypedMapping``

docs/source/libraries.rst

@@ -482,8 +482,7 @@ the original signature of the decorated function.
 
 Decorators that mutate the signature of the decorated function present
 challenges for type annotations. The ``ParamSpec`` and ``Concatenate``
-mechanisms described in `PEP
-612 <https://www.python.org/dev/peps/pep-0612/>`__ provide some help
+mechanisms described in :pep:`612` provide some help
 here, but these are available only in Python 3.10 and newer. More
 complex signature mutations may require type annotations that erase the
 original signature, thus blinding type checkers and other tools that
@@ -495,7 +494,7 @@ Generic Classes and Functions
 
 Classes and functions that can operate in a generic manner on various
 types should declare themselves as generic using the mechanisms
-described in `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__.
+described in :pep:`484`.
 This includes the use of ``TypeVar`` symbols. Typically, a ``TypeVar``
 should be private to the file that declares it, and should therefore
 begin with an underscore.
@@ -507,7 +506,7 @@ Type aliases are symbols that refer to other types. Generic type aliases
 (those that refer to unspecialized generic classes) are supported by
 most type checkers.
 
-`PEP 613 <https://www.python.org/dev/peps/pep-0613/>`__ provides a way
+:pep:`613` provides a way
 to explicitly designate a symbol as a type alias using the new TypeAlias
 annotation.
 
@@ -556,25 +555,23 @@ Final Classes and Methods
 -------------------------
 
 Classes that are not intended to be subclassed should be decorated as
-``@final`` as described in `PEP
-591 <https://www.python.org/dev/peps/pep-0591/>`__. The same decorator
+``@final`` as described in :pep:`591`. The same decorator
 can also be used to specify methods that cannot be overridden by
 subclasses.
 
 Literals
 --------
 
 Type annotations should make use of the Literal type where appropriate,
-as described in `PEP 586 <https://www.python.org/dev/peps/pep-0586/>`__.
+as described in :pep:`586`.
 Literals allow for more type specificity than their non-literal
 counterparts.
 
 Constants
 ---------
 
 Constant values (those that are read-only) can be specified using the
-Final annotation as described in `PEP
-591 <https://www.python.org/dev/peps/pep-0591/>`__.
+Final annotation as described in :pep:`591`.
 
 Type checkers will also typically treat variables that are named using
 all upper-case characters as constants.
@@ -606,16 +603,13 @@ Typed Dictionaries, Data Classes, and Named Tuples
 If your library runs only on newer versions of Python, you are
 encouraged to use some of the new type-friendly classes.
 
-NamedTuple (described in `PEP
-484 <https://www.python.org/dev/peps/pep-0484/>`__) is preferred over
+NamedTuple (described in :pep:`484`) is preferred over
 namedtuple.
 
-Data classes (described in `PEP
-557 <https://www.python.org/dev/peps/pep-0557/>`__) is preferred over
+Data classes (described in :pep:`557`) is preferred over
 untyped dictionaries.
 
-TypedDict (described in `PEP
-589 <https://www.python.org/dev/peps/pep-0589/>`__) is preferred over
+TypedDict (described in :pep:`589`) is preferred over
 untyped dictionaries.
 
 Compatibility with Older Python Versions
@@ -646,9 +640,9 @@ Type Comment Annotations
 ------------------------
 
 Python 3.0 introduced syntax for parameter and return type annotations,
-as specified in `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__.
+as specified in :pep:`484`.
 Python 3.6 introduced support for variable type annotations, as
-specified in `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`__.
+specified in :pep:`526`.
 
 If you need to support older versions of Python, type annotations can
 still be provided as “type comments”. These comments take the form #
@@ -710,8 +704,7 @@ Docstrings
 ==========
 
 Docstrings should be provided for all classes, functions, and methods in
-the interface. They should be formatted according to `PEP
-257 <https://www.python.org/dev/peps/pep-0257/>`__.
+the interface. They should be formatted according to :pep:`257`.
 
 There is currently no single agreed-upon standard for function and
 method docstrings, but several common variants have emerged. We

docs/source/stubs.rst

@@ -52,10 +52,10 @@ Type checker authors are encouraged to support syntax features from
 post-3.7 Python versions, although type stub authors should not use such
 features if they wish to maintain compatibility with all type checkers.
 
-For example, Python 3.7 added the ``async`` keyword (see PEP 492 [#pep492]_).
+For example, Python 3.7 added the ``async`` keyword (see :pep:`492`).
 Stub authors should use it to mark coroutines, even if the implementation
 still uses the ``@coroutine`` decorator. On the other hand, type stubs should
-not use the positional-only syntax from PEP 570 [#pep570]_, introduced in
+not use the positional-only syntax from :pep:`570`, introduced in
 Python 3.8, although type checker authors are encouraged to support it.
 
 Stubs are treated as if ``from __future__ import annotations`` is enabled.
@@ -72,7 +72,7 @@ Distribution
 ============
 
 Type stubs can be distributed with or separately from the implementation;
-see PEP 561 [#pep561]_ for more information. The
+see :pep:`561` for more information. The
 `typeshed <https://github.com/python/typeshed>`_ project
 includes stubs for Python's standard library and several third-party
 packages. The stubs for the standard library are usually distributed with type checkers and do not
@@ -112,7 +112,7 @@ Standard Python comments are accepted everywhere Python syntax allows them.
 Two kinds of structured comments are accepted:
 
 * A ``# type: X`` comment at the end of a line that defines a variable,
-  declaring that the variable has type ``X``. However, PEP 526-style [#pep526]_
+  declaring that the variable has type ``X``. However, :pep:`526`-style
   variable annotations are preferred over type comments.
 * A ``# type: ignore`` comment at the end of any line, which suppresses all type
   errors in that line. The type checker mypy supports suppressing certain
@@ -124,7 +124,7 @@ Imports
 
 Type stubs distinguish between imports that are re-exported and those
 that are only used internally. Imports are re-exported if they use one of these
-forms:[#pep484]_
+forms (:pep:`484`):
 
 * ``import X as X``
 * ``from Y import X as X``
@@ -175,7 +175,7 @@ Type checkers support cyclic imports in stub files.
 Built-in Generics
 -----------------
 
-PEP 585 [#pep585]_ built-in generics are supported and should be used instead
+:pep:`585` built-in generics are supported and should be used instead
 of the corresponding types from ``typing``::
 
     from collections import defaultdict
@@ -268,17 +268,17 @@ Functions and Methods
 
 Function and method definition syntax follows general Python syntax.
 Unless an argument name is prefixed with two underscores (but not suffixed
-with two underscores), it can be used as a keyword argument [#pep484]_::
+with two underscores), it can be used as a keyword argument (:pep:`484`)::
 
     # x is positional-only
     # y can be used positionally or as keyword argument
     # z is keyword-only
     def foo(__x, y, *, z): ...
 
-PEP 570 [#pep570]_ style positional-only parameters are currently not
+:pep:`570` style positional-only parameters are currently not
 supported.
 
-If an argument or return type is unannotated, per PEP 484 [#pep484]_ its
+If an argument or return type is unannotated, per :pep:`484` its
 type is assumed to be ``Any``. It is preferred to leave unknown
 types unannotated rather than explicitly marking them as ``Any``, as some
 type checkers can optionally warn about unannotated arguments.
@@ -314,7 +314,7 @@ But::
         @classmethod
         def create_it(cls: _T) -> _T: ...  # cls has type _T
 
-PEP 612 [#pep612]_ parameter specification variables (``ParamSpec``)
+:pep:`612` parameter specification variables (``ParamSpec``)
 are supported in argument and return types::
 
     _P = ParamSpec("_P")
@@ -325,7 +325,7 @@ are supported in argument and return types::
 However, ``Concatenate`` from PEP 612 is not yet supported; nor is using
 a ``ParamSpec`` to parameterize a generic class.
 
-PEP 647 [#pep647]_ type guards are supported.
+:pep:`647` type guards are supported.
 
 Using a function or method body other than the ellipsis literal is currently
 unspecified. Stub authors may experiment with other bodies, but it is up to
@@ -355,7 +355,7 @@ Aliases and NewType
 -------------------
 
 Type checkers should accept module-level type aliases, optionally using
-``TypeAlias`` (PEP 613 [#pep613]_), e.g.::
+``TypeAlias`` (:pep:`613`), e.g.::
 
   _IntList = list[int]
   _StrList: TypeAlias = list[str]
@@ -370,7 +370,7 @@ e.g.::
       def f(self) -> int: ...
       g = f
 
-A type alias may contain type variables. As per PEP 484 [#pep484]_,
+A type alias may contain type variables. As per :pep:`484`,
 all type variables must be substituted when the alias is used::
 
   _K = TypeVar("_K")
@@ -521,7 +521,7 @@ Unsupported Features
 Currently, the following features are not supported by all type checkers
 and should not be used in stubs:
 
-* Positional-only argument syntax (PEP 570 [#pep570]_). Instead, use
+* Positional-only argument syntax (:pep:`570`). Instead, use
   the syntax described in the section :ref:`supported-functions`.
   [#ts-4972]_
 
@@ -607,7 +607,7 @@ Structural Types
 
 As seen in the example with ``_Readable`` in the previous section, a common use
 of stub-only objects is to model types that are best described by their
-structure. These objects are called protocols [#pep544]_, and it is encouraged
+structure. These objects are called protocols (:pep:`544`), and it is encouraged
 to use them freely to describe simple structural types.
 
 It is `recommended <#private-definitions>`_ to prefix stubs-only object names with ``_``.
@@ -765,8 +765,8 @@ who wish to provide a consistent style for type stubs. Type checkers
 should not reject stubs that do not follow these recommendations, but
 linters can warn about them.
 
-Stub files should generally follow the Style Guide for Python Code (PEP 8)
-[#pep8]_ and the :ref:`best-practices`. There are a few exceptions, outlined below, that take the
+Stub files should generally follow the Style Guide for Python Code (:pep:`8`)
+and the :ref:`best-practices`. There are a few exceptions, outlined below, that take the
 different structure of stub files into account and are aimed to create
 more concise files.
 
@@ -989,23 +989,6 @@ No::
 References
 ==========
 
-PEPs
-----
-
-.. [#pep8] PEP 8 -- Style Guide for Python Code, van Rossum et al. (https://www.python.org/dev/peps/pep-0008/)
-.. [#pep484] PEP 484 -- Type Hints, van Rossum et al. (https://www.python.org/dev/peps/pep-0484)
-.. [#pep492] PEP 492 -- Coroutines with async and await syntax, Selivanov (https://www.python.org/dev/peps/pep-0492/)
-.. [#pep526] PEP 526 -- Syntax for Variable Annotations, Gonzalez et al. (https://www.python.org/dev/peps/pep-0526)
-.. [#pep544] PEP 544 -- Protocols: Structural Subtyping, Levkivskyi et al. (https://www.python.org/dev/peps/pep-0544)
-.. [#pep561] PEP 561 -- Distributing and Packaging Type Information, Smith (https://www.python.org/dev/peps/pep-0561)
-.. [#pep570] PEP 570 -- Python Positional-Only Parameters, Hastings et al. (https://www.python.org/dev/peps/pep-0570)
-.. [#pep585] PEP 585 -- Type Hinting Generics In Standard Collections, Langa (https://www.python.org/dev/peps/pep-0585)
-.. [#pep604] PEP 604 -- Allow writing union types as X | Y, Prados and Moss (https://www.python.org/dev/peps/pep-0604)
-.. [#pep612] PEP 612 -- Parameter Specification Variables, Mendoza (https://www.python.org/dev/peps/pep-0612)
-.. [#pep613] PEP 613 -- Explicit Type Aliases, Zhu (https://www.python.org/dev/peps/pep-0613)
-.. [#pep647] PEP 647 -- User-Defined Type Guards, Traut (https://www.python.org/dev/peps/pep-0647)
-.. [#pep3107] PEP 3107 -- Function Annotations, Winter and Lownds (https://www.python.org/dev/peps/pep-3107)
-
 Bugs
 ----