diff --git a/doc/tutorial/automatic-doc-generation.rst b/doc/tutorial/automatic-doc-generation.rst index 6a56dbd3afa..b47673d1832 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 ` 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 `_ -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 ` provides this functionality. diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 4c3aac0041d..ace164f1e24 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 eb07def8bd2..1b9c8226872 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 - `__. + ``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 aacc768dc2b..6f82a2e5f3e 100644 --- a/doc/usage/extensions/example_google.py +++ b/doc/usage/extensions/example_google.py @@ -45,7 +45,7 @@ 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 f7722972ed0..ebe98bd821d 100644 --- a/doc/usage/extensions/example_numpy.py +++ b/doc/usage/extensions/example_numpy.py @@ -55,7 +55,7 @@ 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 b18b3c466ce..f372d641ded 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.