[3.15] gh-105812: Make use of the Sphinx deco role in documentation (GH-139598) (#154979)

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Author: hugovk

Doc/c-api/exceptions.rst

@@ -1056,7 +1056,7 @@ Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requ
 special recursion handling.  In addition to protecting the stack,
 :c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
 following two functions facilitate this functionality.  Effectively,
-these are the C equivalent to :func:`reprlib.recursive_repr`.
+these are the C equivalent to :deco:`reprlib.recursive_repr`.
 
 .. c:function:: int Py_ReprEnter(PyObject *object)
 

Doc/c-api/structures.rst

@@ -454,8 +454,8 @@ method.
 
    The method will be passed the type object as the first parameter rather
    than an instance of the type.  This is used to create *class methods*,
-   similar to what is created when using the :func:`classmethod` built-in
-   function.
+   similar to what is created when using the :deco:`classmethod` built-in
+   decorator.
 
 
 .. c:macro:: METH_STATIC
@@ -464,7 +464,7 @@ method.
 
    The method will be passed ``NULL`` as the first parameter rather than an
    instance of the type.  This is used to create *static methods*, similar to
-   what is created when using the :func:`staticmethod` built-in function.
+   what is created when using the :deco:`staticmethod` built-in decorator.
 
 One other constant controls whether a method is loaded in place of another
 definition with the same method name.

Doc/deprecations/pending-removal-in-3.15.rst

@@ -82,7 +82,7 @@ Pending removal in Python 3.15
     Use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``
     to create a TypedDict with zero field.
 
-  * The :func:`!typing.no_type_check_decorator` decorator function
+  * The :deco:`!typing.no_type_check_decorator` decorator function
     has been deprecated since Python 3.13.
     After eight years in the :mod:`typing` module,
     it has yet to be supported by any major type checker.

Doc/faq/programming.rst

@@ -2003,7 +2003,7 @@ How do I cache method calls?
 ----------------------------
 
 The two principal tools for caching methods are
-:func:`functools.cached_property` and :func:`functools.lru_cache`.  The
+:deco:`functools.cached_property` and :deco:`functools.lru_cache`.  The
 former stores results at the instance level and the latter at the class
 level.
 

Doc/glossary.rst

@@ -416,7 +416,7 @@ Glossary
    decorator
       A function returning another function, usually applied as a function
       transformation using the ``@wrapper`` syntax.  Common examples for
-      decorators are :func:`classmethod` and :func:`staticmethod`.
+      decorators are :deco:`classmethod` and :deco:`staticmethod`.
 
       The decorator syntax is merely syntactic sugar, the following two
       function definitions are semantically equivalent::
@@ -689,7 +689,7 @@ Glossary
       determined by the dispatch algorithm.
 
       See also the :term:`single dispatch` glossary entry, the
-      :func:`functools.singledispatch` decorator, and :pep:`443`.
+      :deco:`functools.singledispatch` decorator, and :pep:`443`.
 
    generic type
       A :term:`type` that can be parameterized; typically a

Doc/howto/annotations.rst

@@ -152,7 +152,7 @@ on an arbitrary object ``o``:
   as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
   when calling :func:`eval`.
 * If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
-  :func:`functools.wraps`, or :func:`functools.partial`, iteratively
+  :deco:`functools.wraps`, or :func:`functools.partial`, iteratively
   unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
   appropriate, until you have found the root unwrapped function.
 * If ``o`` is a callable (but not a class), use

Doc/howto/descriptor.rst

@@ -25,7 +25,7 @@ This guide has four major sections:
 4) The last section has pure Python equivalents for built-in descriptors that
    are written in C.  Read this if you're curious about how functions turn
    into bound methods or about the implementation of common tools like
-   :func:`classmethod`, :func:`staticmethod`, :func:`property`, and
+   :deco:`classmethod`, :deco:`staticmethod`, :deco:`property`, and
    :term:`__slots__`.
 
 
@@ -314,8 +314,8 @@ Descriptors invert that relationship and allow the data being looked-up to
 have a say in the matter.
 
 Descriptors are used throughout the language.  It is how functions turn into
-bound methods.  Common tools like :func:`classmethod`, :func:`staticmethod`,
-:func:`property`, and :func:`functools.cached_property` are all implemented as
+bound methods.  Common tools like :deco:`classmethod`, :deco:`staticmethod`,
+:deco:`property`, and :deco:`functools.cached_property` are all implemented as
 descriptors.
 
 
@@ -1323,7 +1323,7 @@ example calls are unexciting:
     30
 
 Using the non-data descriptor protocol, a pure Python version of
-:func:`staticmethod` would look like this:
+:deco:`staticmethod` would look like this:
 
 .. testcode::
 
@@ -1463,7 +1463,7 @@ Now a new dictionary of unique keys can be constructed like this:
     {'a': None, 'b': None, 'r': None, 'c': None, 'd': None}
 
 Using the non-data descriptor protocol, a pure Python version of
-:func:`classmethod` would look like this:
+:deco:`classmethod` would look like this:
 
 .. testcode::
 
@@ -1601,7 +1601,7 @@ matters when a large number of instances are going to be created.
 4. Improves speed.  Reading instance variables is 35% faster with
 ``__slots__`` (as measured with Python 3.10 on an Apple M1 processor).
 
-5. Blocks tools like :func:`functools.cached_property` which require an
+5. Blocks tools like :deco:`functools.cached_property` which require an
 instance dictionary to function correctly:
 
 .. testcode::

Doc/howto/enum.rst

@@ -256,7 +256,7 @@ Ensuring unique enumeration values
 ----------------------------------
 
 By default, enumerations allow multiple names as aliases for the same value.
-When this behavior isn't desired, you can use the :func:`unique` decorator::
+When this behavior isn't desired, you can use the :deco:`unique` decorator::
 
     >>> from enum import Enum, unique
     >>> @unique
@@ -509,7 +509,7 @@ to use the standard :func:`repr`.
 
 .. note::
 
-   Adding :func:`~dataclasses.dataclass` decorator to :class:`Enum`
+   Adding :deco:`~dataclasses.dataclass` decorator to :class:`Enum`
    and its subclasses is not supported. It will not raise any errors,
    but it will produce very strange results at runtime, such as members
    being equal to each other::

Doc/howto/sorting.rst

@@ -372,7 +372,7 @@ Odds and Ends
   :meth:`~object.__lt__` is not implemented (see :func:`object.__lt__`
   for details on the mechanics).  To avoid surprises, :pep:`8`
   recommends that all six comparison methods be implemented.
-  The :func:`~functools.total_ordering` decorator is provided to make that
+  The :deco:`~functools.total_ordering` decorator is provided to make that
   task easier.
 
 * Key functions need not depend directly on the objects being sorted. A key

Doc/library/abc.rst

@@ -166,17 +166,17 @@ The :mod:`!abc` module also provides the following decorator:
    or is derived from it.  A class that has a metaclass derived from
    :class:`!ABCMeta` cannot be instantiated unless all of its abstract methods
    and properties are overridden.  The abstract methods can be called using any
-   of the normal 'super' call mechanisms.  :func:`!abstractmethod` may be used
+   of the normal 'super' call mechanisms.  :deco:`!abstractmethod` may be used
    to declare abstract methods for properties and descriptors.
 
    Dynamically adding abstract methods to a class, or attempting to modify the
    abstraction status of a method or class once it is created, are only
    supported using the :func:`update_abstractmethods` function.  The
-   :func:`!abstractmethod` only affects subclasses derived using regular
+   :deco:`!abstractmethod` only affects subclasses derived using regular
    inheritance; "virtual subclasses" registered with the ABC's
    :meth:`~ABCMeta.register` method are not affected.
 
-   When :func:`!abstractmethod` is applied in combination with other method
+   When :deco:`!abstractmethod` is applied in combination with other method
    descriptors, it should be applied as the innermost decorator, as shown in
    the following usage examples::
 
@@ -214,7 +214,7 @@ The :mod:`!abc` module also provides the following decorator:
    the descriptor must identify itself as abstract using
    :attr:`!__isabstractmethod__`. In general, this attribute should be ``True``
    if any of the methods used to compose the descriptor are abstract. For
-   example, Python's built-in :class:`property` does the equivalent of::
+   example, Python's built-in :deco:`property` does the equivalent of::
 
       class Descriptor:
           ...
@@ -238,13 +238,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`classmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`classmethod` with
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`classmethod`, indicating an abstract
-   classmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :class:`classmethod`, indicating an abstract
+   classmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`classmethod` decorator
+   This special case is deprecated, as the :deco:`classmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -259,13 +259,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`staticmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`staticmethod` with
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`staticmethod`, indicating an abstract
-   staticmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :class:`staticmethod`, indicating an abstract
+   staticmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`staticmethod` decorator
+   This special case is deprecated, as the :deco:`staticmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -279,14 +279,14 @@ The :mod:`!abc` module also supports the following legacy decorators:
 .. decorator:: abstractproperty
 
    .. deprecated:: 3.3
-       It is now possible to use :class:`property`, :meth:`property.getter`,
-       :meth:`property.setter` and :meth:`property.deleter` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`property`, :deco:`property.getter`,
+       :deco:`property.setter` and :deco:`property.deleter` with
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`property`, indicating an abstract
+   A subclass of the built-in :class:`property`, indicating an abstract
    property.
 
-   This special case is deprecated, as the :func:`property` decorator
+   This special case is deprecated, as the :deco:`property` decorator
    is now correctly identified as abstract when applied to an abstract
    method::