From 5cb2b24f8ed228e8bb606deecb0a66b36537dd56 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Fri, 12 Aug 2022 21:26:08 -0400 Subject: [PATCH 1/2] Update reST references to sections --- doc/format.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 56e4a4f3..be7dcb7f 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -31,7 +31,7 @@ Use a code checker: * pyflakes_: a tool to check Python code for errors by parsing the source file instead of importing it. * pycodestyle_: (formerly ``pep8``) a tool to check Python code against - some of the style conventions in PEP 8. + some of the style conventions in :pep:`8`. * flake8_: a tool that glues together ``pycodestyle``, ``pyflakes``, ``mccabe`` to check the style and quality of Python code. * vim-flake8_: a ``flake8`` plugin for Vim. @@ -291,10 +291,12 @@ Support for the :ref:`Yields ` section was added in `numpydoc ``````````` Explanation of parameters passed to a generator's ``.send()`` method, -formatted as for Parameters, above. Since, like for Yields and Returns, a -single object is always passed to the method, this may describe either the -single parameter, or positional arguments passed as a tuple. If a docstring -includes Receives it must also include Yields. +formatted as for :ref:`Parameters `, above. Since, like for +:ref:`Yields ` and :ref:`Returns `, a single object is +always passed to the method, this may describe either the single parameter, +or positional arguments passed as a tuple. If a docstring +includes :ref:`Receives ` it must also include +:ref:`Yields `. 8. Other Parameters ``````````````````` @@ -321,7 +323,7 @@ that are non-obvious or have a large chance of getting raised. ````````` An optional section detailing which warnings get raised and -under what conditions, formatted similarly to Raises. +under what conditions, formatted similarly to :ref:`Raises `. 11. Warnings ```````````` @@ -545,8 +547,8 @@ Documenting classes Class docstring ``````````````` -Use the same sections as outlined above (all except ``Returns`` are -applicable). The constructor (``__init__``) should also be documented +Use the same sections as outlined above (all except :ref:`Returns ` +are applicable). The constructor (``__init__``) should also be documented here, the :ref:`Parameters ` section of the docstring details the constructor's parameters. From d2dc8bfaa049d64e0229045dbe9fdeb09f688720 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Fri, 12 Aug 2022 21:39:08 -0400 Subject: [PATCH 2/2] Add in reST labels to sections --- doc/format.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/format.rst b/doc/format.rst index be7dcb7f..6e44a566 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -287,11 +287,13 @@ takes the same form as the :ref:`Returns ` section:: Support for the :ref:`Yields ` section was added in `numpydoc `_ version 0.6. +.. _receives: + 7. Receives ``````````` Explanation of parameters passed to a generator's ``.send()`` method, -formatted as for :ref:`Parameters `, above. Since, like for +formatted as for :ref:`Parameters `, above. Since, like for :ref:`Yields ` and :ref:`Returns `, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring @@ -305,6 +307,8 @@ An optional section used to describe infrequently used parameters. It should only be used if a function has a large number of keyword parameters, to prevent cluttering the :ref:`Parameters ` section. +.. _raises: + 9. Raises `````````