Merge pull request #10297 from tk0miya/10288_refactor_docs

doc: Use :pep: role to refer PEP documents

6 files changed, 15 insertions, 28 deletions

diff --git a/doc/tutorial/automatic-doc-generation.rst b/doc/tutorial/automatic-doc-generation.rst
index 6a56dbd3a..b47673d18 100644
--- a/doc/tutorial/automatic-doc-generation.rst
+++ b/doc/tutorial/automatic-doc-generation.rst
@@ -4,10 +4,9 @@ Automatic documentation generation from code
 In the :ref:`previous section <tutorial-describing-objects>` of the tutorial
 you manually documented a Python function in Sphinx. However, the description
 was out of sync with the code itself, since the function signature was not
-the same. Besides, it would be nice to reuse `Python
-docstrings <https://peps.python.org/pep-0257/#what-is-a-docstring>`_
-in the documentation, rather than having to write the information in two
-places.
+the same. Besides, it would be nice to reuse :pep:`Python docstrings
+<257#what-is-a-docstring>` in the documentation, rather than having to write
+the information in two places.
 
 Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this
 functionality.
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 4c3aac004..ace164f1e 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -634,8 +634,8 @@ There are also config values that you can set:
    full-qualified object name.  It is used to keep type aliases not evaluated in
    the document.  Defaults to empty (``{}``).
 
-   The type aliases are only available if your program enables `Postponed
-   Evaluation of Annotations (PEP 563)`__ feature via ``from __future__ import
+   The type aliases are only available if your program enables :pep:`Postponed
+   Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
    annotations``.
 
    For example, there is code using a type alias::
@@ -662,7 +662,6 @@ There are also config values that you can set:
 
         ...
 
-   .. __: https://peps.python.org/pep-0563/
    .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
    .. versionadded:: 3.3
 
diff --git a/doc/usage/extensions/doctest.rst b/doc/usage/extensions/doctest.rst
index eb07def8b..1b9c82268 100644
--- a/doc/usage/extensions/doctest.rst
+++ b/doc/usage/extensions/doctest.rst
@@ -93,8 +93,8 @@ a comma-separated list of group names.
      * ``<``, ``>``: Exclusive ordered comparison clause
      * ``===``: Arbitrary equality clause.
 
-     ``pyversion`` option is followed `PEP-440: Version Specifiers
-     <https://peps.python.org/pep-0440/#version-specifiers>`__.
+     ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+     <440#version-specifiers>`.
 
      .. versionadded:: 1.6
 
diff --git a/doc/usage/extensions/example_google.py b/doc/usage/extensions/example_google.py
index aacc768dc..6f82a2e5f 100644
--- a/doc/usage/extensions/example_google.py
+++ b/doc/usage/extensions/example_google.py
@@ -45,7 +45,7 @@ on the first line, separated by a colon.
 def function_with_types_in_docstring(param1, param2):
     """Example function with types documented in the docstring.
 
-    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    :pep:`484` type annotations are supported. If attribute, parameter, and
     return types are annotated according to `PEP 484`_, they do not need to be
     included in the docstring:
 
@@ -55,10 +55,6 @@ def function_with_types_in_docstring(param1, param2):
 
     Returns:
         bool: The return value. True for success, False otherwise.
-
-    .. _PEP 484:
-        https://peps.python.org/pep-0484/
-
     """
 
 
@@ -311,4 +307,4 @@ class ExamplePEP526Class:
     """
 
     attr1: str
-    attr2: int
\ No newline at end of file
+    attr2: int
diff --git a/doc/usage/extensions/example_numpy.py b/doc/usage/extensions/example_numpy.py
index f7722972e..ebe98bd82 100644
--- a/doc/usage/extensions/example_numpy.py
+++ b/doc/usage/extensions/example_numpy.py
@@ -55,7 +55,7 @@ on the first line, separated by a colon.
 def function_with_types_in_docstring(param1, param2):
     """Example function with types documented in the docstring.
 
-    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    :pep:`484` type annotations are supported. If attribute, parameter, and
     return types are annotated according to `PEP 484`_, they do not need to be
     included in the docstring:
 
@@ -70,10 +70,6 @@ def function_with_types_in_docstring(param1, param2):
     -------
     bool
         True if successful, False otherwise.
-
-    .. _PEP 484:
-        https://peps.python.org/pep-0484/
-
     """
 
 
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
index b18b3c466..f372d641d 100644
--- a/doc/usage/extensions/napoleon.rst
+++ b/doc/usage/extensions/napoleon.rst
@@ -26,7 +26,7 @@ Are you tired of writing docstrings that look like this::
     :rtype: BufferedFileStorage
 
 `reStructuredText`_ is great, but it creates visually dense, hard to read
-`docstrings`_. Compare the jumble above to the same thing rewritten
+:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
 according to the `Google Python Style Guide`_::
 
     Args:
@@ -50,7 +50,6 @@ the documentation, so it doesn't modify any of the docstrings in your actual
 source code files.
 
 .. _ReStructuredText: https://docutils.sourceforge.io/rst.html
-.. _docstrings: https://peps.python.org/pep-0287/
 .. _Google Python Style Guide:
    https://google.github.io/styleguide/pyguide.html
 .. _Google:
@@ -199,11 +198,11 @@ not be mixed. Choose one style for your project and be consistent with it.
 Type Annotations
 ~~~~~~~~~~~~~~~~
 
-`PEP 484`_ introduced a standard way to express types in Python code.
+:pep:`484` introduced a standard way to express types in Python code.
 This is an alternative to expressing types directly in docstrings.
-One benefit of expressing types according to `PEP 484`_ is that
+One benefit of expressing types according to :pep:`484` is that
 type checkers and IDEs can take advantage of them for static code
-analysis. `PEP 484`_ was then extended by `PEP 526`_ which introduced
+analysis. :pep:`484` was then extended by :pep:`526` which introduced
 a similar way to annotate variables (and attributes).
 
 Google style with Python 3 type annotations::
@@ -267,8 +266,6 @@ Google style with types in docstrings::
    `Python 2/3 compatible annotations`_ aren't currently
    supported by Sphinx and won't show up in the docs.
 
-.. _PEP 484: https://peps.python.org/pep-0484/
-.. _PEP 526: https://peps.python.org/pep-0526/
 .. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 
 
@@ -548,7 +545,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 
 .. confval:: napoleon_attr_annotations
 
-   True to allow using `PEP 526`_ attributes annotations in classes.
+   True to allow using :pep:`526` attributes annotations in classes.
    If an attribute is documented in the docstring without a type and
    has an annotation in the class body, that type is used.