gh-105812: Make use of the Sphinx deco role in documentation, part 1

Doc/c-api/structures.rst

@@ -419,8 +419,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
@@ -429,7 +429,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/faq/programming.rst

@@ -1995,7 +1995,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

@@ -366,7 +366,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::

Doc/howto/descriptor.rst

@@ -28,7 +28,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__`.
 
 
@@ -317,8 +317,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.
 
 
@@ -1326,7 +1326,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::
 
@@ -1466,7 +1466,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::
 
@@ -1604,7 +1604,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

Doc/library/abc.rst

@@ -170,17 +170,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::
 
@@ -218,7 +218,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:
           ...
@@ -242,13 +242,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::
 
@@ -263,13 +263,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::
 
@@ -283,14 +283,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`,
+       It is now possible to use :deco:`property`, :meth:`property.getter`,
        :meth:`property.setter` and :meth:`property.deleter` with
-       :func:`abstractmethod`, making this decorator redundant.
+       :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::
 

Doc/library/bisect.rst

@@ -132,7 +132,7 @@ thoughts in mind:
   they are used.  Consequently, if the search functions are used in a loop,
   the key function may be called again and again on the same array elements.
   If the key function isn't fast, consider wrapping it with
-  :py:func:`functools.cache` to avoid duplicate computations.  Alternatively,
+  :py:deco:`functools.cache` to avoid duplicate computations.  Alternatively,
   consider searching an array of precomputed keys to locate the insertion
   point (as shown in the examples section below).
 

Doc/library/collections.rst

@@ -1216,7 +1216,7 @@ original insertion position is changed and moved to the end::
             self.move_to_end(key)
 
 An :class:`OrderedDict` would also be useful for implementing
-variants of :func:`functools.lru_cache`:
+variants of :deco:`functools.lru_cache`:
 
 .. testcode::
 

Doc/library/contextlib.rst

@@ -88,7 +88,7 @@ Functions and classes provided:
    the exception has been handled, and execution will resume with the statement
    immediately following the :keyword:`!with` statement.
 
-   :func:`contextmanager` uses :class:`ContextDecorator` so the context managers
+   :deco:`contextmanager` uses :class:`ContextDecorator` so the context managers
    it creates can be used as decorators as well as in :keyword:`with` statements.
    When used as a decorator, a new generator instance is implicitly created on
    each function call (this allows the otherwise "one-shot" context managers

Doc/library/ctypes.rst

@@ -446,7 +446,7 @@ object with an :attr:`!_as_parameter_` attribute::
    >>>
 
 If you don't want to store the instance's data in the :attr:`!_as_parameter_`
-instance variable, you could define a :class:`property` which makes the
+instance variable, you could define a :deco:`property` which makes the
 attribute available on request.
 
 

Doc/library/enum.rst

@@ -120,30 +120,30 @@ Module Contents
       :class:`StrEnum` defaults to the lower-cased version of the member name,
       while other Enums default to 1 and increase from there.
 
-   :func:`~enum.property`
+   :deco:`~enum.property`
 
       Allows :class:`Enum` members to have attributes without conflicting with
       member names.  The ``value`` and ``name`` attributes are implemented this
       way.
 
-   :func:`unique`
+   :deco:`unique`
 
       Enum class decorator that ensures only one name is bound to any one value.
 
-   :func:`verify`
+   :deco:`verify`
 
       Enum class decorator that checks user-selectable constraints on an
       enumeration.
 
-   :func:`member`
+   :deco:`member`
 
       Make ``obj`` a member.  Can be used as a decorator.
 
-   :func:`nonmember`
+   :deco:`nonmember`
 
       Do not make ``obj`` a member.  Can be used as a decorator.
 
-   :func:`global_enum`
+   :deco:`global_enum`
 
       Modify the :class:`str() <str>` and :func:`repr` of an enum
       to show its members as belonging to the module instead of its class,
@@ -969,7 +969,7 @@ Utilities and Decorators
 
 .. decorator:: property
 
-   A decorator similar to the built-in *property*, but specifically for
+   A decorator similar to the built-in :deco:`property`, but specifically for
    enumerations.  It allows member attributes to have the same names as members
    themselves.
 

Doc/library/fnmatch.rst

@@ -51,7 +51,7 @@ Unless stated otherwise, "filename string" and "pattern string" either refer to
 functions documented below do not allow to mix a :class:`!bytes` pattern with
 a :class:`!str` filename, and vice-versa.
 
-Finally, note that :func:`functools.lru_cache` with a *maxsize* of 32768
+Finally, note that :deco:`functools.lru_cache` with a *maxsize* of 32768
 is used to cache the (typed) compiled regex patterns in the following
 functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`, :func:`.filterfalse`.
 

Doc/library/functions.rst

@@ -1642,7 +1642,7 @@ are always available.  They are listed here in alphabetical order.
 
    If given, *doc* will be the docstring of the property attribute. Otherwise, the
    property will copy *fget*'s docstring (if it exists).  This makes it possible to
-   create read-only properties easily using :func:`property` as a :term:`decorator`::
+   create read-only properties easily using :deco:`property` as a :term:`decorator`::
 
       class Parrot:
           def __init__(self):
@@ -1883,7 +1883,7 @@ are always available.  They are listed here in alphabetical order.
    be used in the class definition (such as ``f()``).
 
    Static methods in Python are similar to those found in Java or C++. Also, see
-   :func:`classmethod` for a variant that is useful for creating alternate class
+   :deco:`classmethod` for a variant that is useful for creating alternate class
    constructors.
 
    Like all decorators, it is also possible to call ``staticmethod`` as

Doc/library/functools.rst

@@ -34,7 +34,7 @@ The :mod:`functools` module defines the following functions:
    Returns the same as ``lru_cache(maxsize=None)``, creating a thin
    wrapper around a dictionary lookup for the function arguments.  Because it
    never needs to evict old values, this is smaller and faster than
-   :func:`lru_cache` with a size limit.
+   :deco:`lru_cache` with a size limit.
 
    For example::
 
@@ -64,7 +64,7 @@ The :mod:`functools` module defines the following functions:
 
    Transform a method of a class into a property whose value is computed once
    and then cached as a normal attribute for the life of the instance. Similar
-   to :func:`property`, with the addition of caching. Useful for expensive
+   to :deco:`property`, with the addition of caching. Useful for expensive
    computed properties of instances that are otherwise effectively immutable.
 
    Example::
@@ -78,8 +78,8 @@ The :mod:`functools` module defines the following functions:
            def stdev(self):
                return statistics.stdev(self._data)
 
-   The mechanics of :func:`cached_property` are somewhat different from
-   :func:`property`.  A regular property blocks attribute writes unless a
+   The mechanics of :deco:`cached_property` are somewhat different from
+   :deco:`property`.  A regular property blocks attribute writes unless a
    setter is defined. In contrast, a *cached_property* allows writes.
 
    The *cached_property* decorator only runs on lookups and only when an
@@ -111,14 +111,14 @@ The :mod:`functools` module defines the following functions:
    (as such classes don't provide a ``__dict__`` attribute at all).
 
    If a mutable mapping is not available or if space-efficient key sharing is
-   desired, an effect similar to :func:`cached_property` can also be achieved by
-   stacking :func:`property` on top of :func:`lru_cache`. See
-   :ref:`faq-cache-method-calls` for more details on how this differs from :func:`cached_property`.
+   desired, an effect similar to :deco:`cached_property` can also be achieved by
+   stacking :deco:`property` on top of :deco:`lru_cache`. See
+   :ref:`faq-cache-method-calls` for more details on how this differs from :deco:`cached_property`.
 
    .. versionadded:: 3.8
 
    .. versionchanged:: 3.12
-      Prior to Python 3.12, ``cached_property`` included an undocumented lock to
+      Prior to Python 3.12, :deco:`!cached_property` included an undocumented lock to
       ensure that in multi-threaded usage the getter function was guaranteed to
       run only once per instance. However, the lock was per-property, not
       per-instance, which could result in unacceptably high lock contention. In
@@ -712,8 +712,7 @@ The :mod:`functools` module defines the following functions:
             return not arg
 
    The same pattern can be used for other similar decorators:
-   :func:`@staticmethod<staticmethod>`,
-   :func:`@abstractmethod<abc.abstractmethod>`, and others.
+   :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others.
 
    .. versionadded:: 3.8
 
@@ -733,7 +732,7 @@ The :mod:`functools` module defines the following functions:
    function's :attr:`~function.__dict__`, i.e. the instance dictionary).
 
    To allow access to the original function for introspection and other purposes
-   (e.g. bypassing a caching decorator such as :func:`lru_cache`), this function
+   (e.g. bypassing a caching decorator such as :deco:`lru_cache`), this function
    automatically adds a ``__wrapped__`` attribute to the wrapper that refers to
    the function being wrapped.
 

Doc/library/tarfile.rst

@@ -659,7 +659,7 @@ be finalized; only the internally used file object will be closed. See the
    it is best practice to only do so in top-level applications or
    :mod:`site configuration <site>`.
    To set a global default this way, a filter function needs to be wrapped in
-   :func:`staticmethod` to prevent injection of a ``self`` argument.
+   :deco:`staticmethod` to prevent injection of a ``self`` argument.
 
    .. versionchanged:: 3.14
 

Doc/library/unittest.rst

@@ -768,7 +768,7 @@ Test cases
 
       A class method called before tests in an individual class are run.
       ``setUpClass`` is called with the class as the only argument
-      and must be decorated as a :func:`classmethod`::
+      and must be decorated as a :deco:`classmethod`::
 
         @classmethod
         def setUpClass(cls):
@@ -783,7 +783,7 @@ Test cases
 
       A class method called after tests in an individual class have run.
       ``tearDownClass`` is called with the class as the only argument
-      and must be decorated as a :meth:`classmethod`::
+      and must be decorated as a :deco:`classmethod`::
 
         @classmethod
         def tearDownClass(cls):