diff --git a/doc/format.rst b/doc/format.rst index 56e4a4f3..6e44a566 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. @@ -287,14 +287,18 @@ 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 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 ``````````````````` @@ -303,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 ````````` @@ -321,7 +327,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 +551,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.