diff options
| -rw-r--r-- | doc/source/docs/howto_document.rst | 657 |
1 files changed, 22 insertions, 635 deletions
diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst index 7b316546b..35fe95fa4 100644 --- a/doc/source/docs/howto_document.rst +++ b/doc/source/docs/howto_document.rst @@ -1,71 +1,31 @@ .. _howto-document: -==================================== + A Guide to NumPy/SciPy Documentation ==================================== -.. Contents:: - -.. Note:: - - For an accompanying example, see `example.py - <http://github.com/numpy/numpy/blob/master/doc/example.py>`_. - - When using `Sphinx <http://sphinx.pocoo.org/>`__ in combination with the - numpy conventions, you should use the ``numpydoc`` extension so that your - docstrings will be handled correctly. For example, Sphinx will extract the - ``Parameters`` section from your docstring and convert it into a field - list. Using ``numpydoc`` will also avoid the reStructuredText errors produced - by plain Sphinx when it encounters numpy docstring conventions like - section headers (e.g. ``-------------``) that sphinx does not expect to - find in docstrings. - - Some features described in this document require a recent version of - ``numpydoc``. For example, the **Yields** section was added in - ``numpydoc`` 0.6. - - It is available from: - - * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_ - * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_ - - Details of how to use it can be found `here - <https://github.com/numpy/numpydoc/blob/master/README.rst>`__ and - here :ref:`howto_build_docs` - -Overview --------- -We mostly follow the standard Python style conventions as described here: - * `Style Guide for C Code <http://python.org/dev/peps/pep-0007/>`_ - * `Style Guide for Python Code <http://python.org/dev/peps/pep-0008/>`_ - * `Docstring Conventions <http://python.org/dev/peps/pep-0257/>`_ - -Additional PEPs of interest regarding documentation of code: - * `Docstring Processing Framework <http://python.org/dev/peps/pep-0256/>`_ - * `Docutils Design Specification <http://python.org/dev/peps/pep-0258/>`_ +When using `Sphinx <http://sphinx.pocoo.org/>`__ in combination with the +numpy conventions, you should use the ``numpydoc`` extension so that your +docstrings will be handled correctly. For example, Sphinx will extract the +``Parameters`` section from your docstring and convert it into a field +list. Using ``numpydoc`` will also avoid the reStructuredText errors produced +by plain Sphinx when it encounters numpy docstring conventions like +section headers (e.g. ``-------------``) that sphinx does not expect to +find in docstrings. -Use a code checker: - * `pylint <http://www.logilab.org/857>`_ - * `pyflakes <https://pypi.python.org/pypi/pyflakes>`_ - * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>`_ - * `flake8 <https://pypi.python.org/pypi/flake8>`_ - * `vim-flake8 <https://github.com/nvie/vim-flake8>`_ plugin for - automatically checking syntax and style with flake8 +Some features described in this document require a recent version of +``numpydoc``. For example, the **Yields** section was added in +``numpydoc`` 0.6. -The following import conventions are used throughout the NumPy source -and documentation:: +It is available from: - import numpy as np - import matplotlib as mpl - import matplotlib.pyplot as plt +* `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_ +* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_ -Do not abbreviate ``scipy``. There is no motivating use case to -abbreviate it in the real world, so we avoid it in the documentation -to avoid confusion. - -It is not necessary to do ``import numpy as np`` at the beginning of -an example. However, some sub-modules, such as ``fft``, are not -imported by default, and you have to include them explicitly:: +Note that for documentation within numpy, it is not necessary to do +``import numpy as np`` at the beginning of an example. However, some +sub-modules, such as ``fft``, are not imported by default, and you have to +include them explicitly:: import numpy.fft @@ -73,581 +33,8 @@ after which you may use it:: np.fft.fft2(...) -Docstring Standard ------------------- -A documentation string (docstring) is a string that describes a module, -function, class, or method definition. The docstring is a special attribute -of the object (``object.__doc__``) and, for consistency, is surrounded by -triple double quotes, i.e.:: - - """This is the form of a docstring. - - It can be spread over several lines. - - """ - -NumPy, SciPy_, and the scikits follow a common convention for -docstrings that provides for consistency, while also allowing our -toolchain to produce well-formatted reference guides. This document -describes the current community consensus for such a standard. If you -have suggestions for improvements, post them on the `numpy-discussion -list`_. - -Our docstring standard uses `re-structured text (reST) -<http://docutils.sourceforge.net/rst.html>`_ syntax and is rendered -using Sphinx_ (a pre-processor that understands the particular -documentation style we are using). While a rich set of -markup is available, we limit ourselves to a very basic subset, in -order to provide docstrings that are easy to read on text-only -terminals. - -A guiding principle is that human readers of the text are given -precedence over contorting docstrings so our tools produce nice -output. Rather than sacrificing the readability of the docstrings, we -have written pre-processors to assist Sphinx_ in its task. - -The length of docstring lines should be kept to 75 characters to -facilitate reading the docstrings in text terminals. - -Sections --------- -The sections of the docstring are: - -1. **Short summary** - - A one-line summary that does not use variable names or the function - name, e.g. - - :: - - def add(a, b): - """The sum of two numbers. - - """ - - The function signature is normally found by introspection and - displayed by the help function. For some functions (notably those - written in C) the signature is not available, so we have to specify - it as the first line of the docstring:: - - """ - add(a, b) - - The sum of two numbers. - - """ - -2. **Deprecation warning** - - A section (use if applicable) to warn users that the object is deprecated. - Section contents should include: - - * In what NumPy version the object was deprecated, and when it will be - removed. - - * Reason for deprecation if this is useful information (e.g., object - is superseded, duplicates functionality found elsewhere, etc.). - - * New recommended way of obtaining the same functionality. - - This section should use the note Sphinx directive instead of an - underlined section header. - - :: - - .. note:: Deprecated in NumPy 1.6.0 - `ndobj_old` will be removed in NumPy 2.0.0, it is replaced by - `ndobj_new` because the latter works also with array subclasses. - -3. **Extended Summary** - - A few sentences giving an extended description. This section - should be used to clarify *functionality*, not to discuss - implementation detail or background theory, which should rather be - explored in the **Notes** section below. You may refer to the - parameters and the function name, but parameter descriptions still - belong in the **Parameters** section. - -4. **Parameters** - - Description of the function arguments, keywords and their - respective types. - - :: - - Parameters - ---------- - x : type - Description of parameter `x`. - y - Description of parameter `y` (with type not specified) - - Enclose variables in single backticks. The colon must be preceded - by a space, or omitted if the type is absent. - - For the parameter types, be as precise as possible. Below are a - few examples of parameters and their types. - - :: - - Parameters - ---------- - filename : str - copy : bool - dtype : data-type - iterable : iterable object - shape : int or tuple of int - files : list of str - - If it is not necessary to specify a keyword argument, use - ``optional``:: - - x : int, optional - - Optional keyword parameters have default values, which are - displayed as part of the function signature. They can also be - detailed in the description:: - - Description of parameter `x` (the default is -1, which implies summation - over all axes). - - When a parameter can only assume one of a fixed set of values, - those values can be listed in braces, with the default appearing first:: - - order : {'C', 'F', 'A'} - Description of `order`. - - When two or more input parameters have exactly the same type, shape and - description, they can be combined:: - - x1, x2 : array_like - Input arrays, description of `x1`, `x2`. - -5. **Returns** - - Explanation of the returned values and their types. Similar to the - **Parameters** section, except the name of each return value is optional. - The type of each return value is always required:: - - Returns - ------- - int - Description of anonymous integer return value. - - If both the name and type are specified, the **Returns** section takes the - same form as the **Parameters** section:: - - Returns - ------- - err_code : int - Non-zero value indicates error code, or zero on success. - err_msg : str or None - Human readable error message, or None on success. - -6. **Yields** - - Explanation of the yielded values and their types. This is relevant to - generators only. Similar to the **Returns** section in that the name of - each value is optional, but the type of each value is always required:: - - Yields - ------ - int - Description of the anonymous integer return value. - - If both the name and type are specified, the **Yields** section takes the - same form as the **Returns** section:: - - Yields - ------ - err_code : int - Non-zero value indicates error code, or zero on success. - err_msg : str or None - Human readable error message, or None on success. - - Support for the **Yields** section was added in `numpydoc - <https://github.com/numpy/numpydoc>`_ version 0.6. - -7. **Other Parameters** - - 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 **Parameters** section. - -8. **Raises** - - An optional section detailing which errors get raised and under - what conditions:: - - Raises - ------ - LinAlgException - If the matrix is not numerically invertible. - - This section should be used judiciously, i.e., only for errors - that are non-obvious or have a large chance of getting raised. - -9. **See Also** - - An optional section used to refer to related code. This section - can be very useful, but should be used judiciously. The goal is to - direct users to other functions they may not be aware of, or have - easy means of discovering (by looking at the module docstring, for - example). Routines whose docstrings further explain parameters - used by this function are good candidates. - - As an example, for ``numpy.mean`` we would have:: - - See Also - -------- - average : Weighted average - - When referring to functions in the same sub-module, no prefix is - needed, and the tree is searched upwards for a match. - - Prefix functions from other sub-modules appropriately. E.g., - whilst documenting the ``random`` module, refer to a function in - ``fft`` by - - :: - - fft.fft2 : 2-D fast discrete Fourier transform - - When referring to an entirely different module:: - - scipy.random.norm : Random variates, PDFs, etc. - - Functions may be listed without descriptions, and this is - preferable if the functionality is clear from the function name:: - - See Also - -------- - func_a : Function a with its description. - func_b, func_c, func_d - func_e - -10. **Notes** - - An optional section that provides additional information about the - code, possibly including a discussion of the algorithm. This - section may include mathematical equations, written in - `LaTeX <http://www.latex-project.org/>`_ format:: - - The FFT is a fast implementation of the discrete Fourier transform: - - .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n} - - Equations can also be typeset underneath the math directive:: - - The discrete-time Fourier time-convolution property states that - - .. math:: - - x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\ - another equation here - - Math can furthermore be used inline, i.e. - - :: - - The value of :math:`\omega` is larger than 5. - - Variable names are displayed in typewriter font, obtained by using - ``\mathtt{var}``:: - - We square the input parameter `alpha` to obtain - :math:`\mathtt{alpha}^2`. - - Note that LaTeX is not particularly easy to read, so use equations - sparingly. - - Images are allowed, but should not be central to the explanation; - users viewing the docstring as text must be able to comprehend its - meaning without resorting to an image viewer. These additional - illustrations are included using:: - - .. image:: filename - - where filename is a path relative to the reference guide source - directory. - -11. **References** - - References cited in the **notes** section may be listed here, - e.g. if you cited the article below using the text ``[1]_``, - include it as in the list as follows:: - - .. [1] O. McNoleg, "The integration of GIS, remote sensing, - expert systems and adaptive co-kriging for environmental habitat - modelling of the Highland Haggis using object-oriented, fuzzy-logic - and neural-network techniques," Computers & Geosciences, vol. 22, - pp. 585-588, 1996. - - which renders as [1]_ - - .. [1] O. McNoleg, "The integration of GIS, remote sensing, - expert systems and adaptive co-kriging for environmental habitat - modelling of the Highland Haggis using object-oriented, fuzzy-logic - and neural-network techniques," Computers & Geosciences, vol. 22, - pp. 585-588, 1996. - - Referencing sources of a temporary nature, like web pages, is - discouraged. References are meant to augment the docstring, but - should not be required to understand it. References are numbered, starting - from one, in the order in which they are cited. - -12. **Examples** - - An optional section for examples, using the `doctest - <http://docs.python.org/library/doctest.html>`_ format. - This section is meant to illustrate usage, not to provide a - testing framework -- for that, use the ``tests/`` directory. - While optional, this section is very strongly encouraged. - - When multiple examples are provided, they should be separated by - blank lines. Comments explaining the examples should have blank - lines both above and below them:: - - >>> np.add(1, 2) - 3 - - Comment explaining the second example - - >>> np.add([1, 2], [3, 4]) - array([4, 6]) - - For tests with a result that is random or platform-dependent, mark the - output as such:: - - >>> import numpy.random - >>> np.random.rand(2) - array([ 0.35773152, 0.38568979]) #random - - You can run examples as doctests using:: - - >>> np.test(doctests=True) - >>> np.linalg.test(doctests=True) # for a single module - - In IPython it is also possible to run individual examples simply by - copy-pasting them in doctest mode:: - - In [1]: %doctest_mode - Exception reporting mode: Plain - Doctest mode is: ON - >>> %paste - import numpy.random - np.random.rand(2) - ## -- End pasted text -- - array([ 0.8519522 , 0.15492887]) - - - It is not necessary to use the doctest markup ``<BLANKLINE>`` to - indicate empty lines in the output. Note that the option to run - the examples through ``numpy.test`` is provided for checking if the - examples work, not for making the examples part of the testing framework. - - The examples may assume that ``import numpy as np`` is executed before - the example code in *numpy*. Additional examples may make use of - *matplotlib* for plotting, but should import it explicitly, e.g., - ``import matplotlib.pyplot as plt``. All other imports, including the - demonstrated function, must be explicit. - - -Documenting classes -------------------- - -Class docstring -``````````````` -Use the same sections as outlined above (all except ``Returns`` are -applicable). The constructor (``__init__``) should also be documented -here, the **Parameters** section of the docstring details the constructors -parameters. - -An **Attributes** section, located below the **Parameters** section, -may be used to describe non-method attributes of the class:: - - Attributes - ---------- - x : float - The X coordinate. - y : float - The Y coordinate. - -Attributes that are properties and have their own docstrings can be -simply listed by name:: - - Attributes - ---------- - real - imag - x : float - The X coordinate - y : float - The Y coordinate - -In general, it is not necessary to list class methods. Those that are -not part of the public API have names that start with an underscore. -In some cases, however, a class may have a great many methods, of -which only a few are relevant (e.g., subclasses of ndarray). Then, it -becomes useful to have an additional **Methods** section:: - - class Photo(ndarray): - """ - Array with associated photographic information. - - ... - - Attributes - ---------- - exposure : float - Exposure in seconds. - - Methods - ------- - colorspace(c='rgb') - Represent the photo in the given colorspace. - gamma(n=1.0) - Change the photo's gamma exposure. - - """ - -If it is necessary to explain a private method (use with care!), it can -be referred to in the **Extended Summary** or the **Notes** section. -Do not list private methods in the **methods** section. - -Note that `self` is *not* listed as the first parameter of methods. - -Method docstrings -````````````````` -Document these as you would any other function. Do not include -``self`` in the list of parameters. If a method has an equivalent function -(which is the case for many ndarray methods for example), the function -docstring should contain the detailed documentation, and the method docstring -should refer to it. Only put brief summary and **See Also** sections in the -method docstring. The method should use a **Returns** or **Yields** section, -as appropriate. - - -Documenting class instances ---------------------------- -Instances of classes that are part of the NumPy API (for example `np.r_` -`np,c_`, `np.index_exp`, etc.) may require some care. To give these -instances a useful docstring, we do the following: - -* Single instance: If only a single instance of a class is exposed, - document the class. Examples can use the instance name. - -* Multiple instances: If multiple instances are exposed, docstrings - for each instance are written and assigned to the instances' - ``__doc__`` attributes at run time. The class is documented as usual, and - the exposed instances can be mentioned in the **Notes** and **See Also** - sections. - - -Documenting generators ----------------------- -Generators should be documented just as functions are documented. The -only difference is that one should use the **Yields** section instead -of the **Returns** section. Support for the **Yields** section was added in -`numpydoc <https://github.com/numpy/numpydoc>`_ version 0.6. - - -Documenting constants ---------------------- -Use the same sections as outlined for functions where applicable:: - - 1. summary - 2. extended summary (optional) - 3. see also (optional) - 4. references (optional) - 5. examples (optional) - -Docstrings for constants will not be visible in text terminals -(constants are of immutable type, so docstrings can not be assigned -to them like for for class instances), but will appear in the -documentation built with Sphinx. - - -Documenting modules -------------------- -Each module should have a docstring with at least a summary line. Other -sections are optional, and should be used in the same order as for documenting -functions when they are appropriate:: - - 1. summary - 2. extended summary - 3. routine listings - 4. see also - 5. notes - 6. references - 7. examples - -Routine listings are encouraged, especially for large modules, for which it is -hard to get a good overview of all functionality provided by looking at the -source file(s) or the ``__all__`` dict. - -Note that license and author info, while often included in source files, do not -belong in docstrings. - - -Other points to keep in mind ----------------------------- -* Equations : as discussed in the **Notes** section above, LaTeX formatting - should be kept to a minimum. Often it's possible to show equations as - Python code or pseudo-code instead, which is much more readable in a - terminal. For inline display use double backticks (like ``y = np.sin(x)``). - For display with blank lines above and below, use a double colon and indent - the code, like:: - - end of previous sentence:: - - y = np.sin(x) - -* Notes and Warnings : If there are points in the docstring that deserve - special emphasis, the reST directives for a note or warning can be used - in the vicinity of the context of the warning (inside a section). Syntax:: - - .. warning:: Warning text. - - .. note:: Note text. - - Use these sparingly, as they do not look very good in text terminals - and are not often necessary. One situation in which a warning can - be useful is for marking a known bug that is not yet fixed. - -* array_like : For functions that take arguments which can have not only - a type `ndarray`, but also types that can be converted to an ndarray - (i.e. scalar types, sequence types), those arguments can be documented - with type `array_like`. - -Common reST concepts --------------------- -For paragraphs, indentation is significant and indicates indentation in the -output. New paragraphs are marked with a blank line. - -Use ``*italics*``, ``**bold**`` and ````monospace```` if needed in any -explanations -(but not for variable names and doctest code or multi-line code). -Variable, module, function, and class names should be written between -single back-ticks (```numpy```). - -A more extensive example of reST markup can be found in `this example -document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_; -the `quick reference -<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ is -useful while editing. - -Line spacing and indentation are significant and should be carefully -followed. - -Conclusion ----------- +.. rubric:: **For convenience the** `formatting standard`_ **is included below.** -`An example <http://github.com/numpy/numpy/blob/master/doc/example.py>` of the -format shown here is available. Refer to -:ref:`howto-build-docs` on how to use Sphinx_ to build -the manual. +.. include:: ../../sphinxext/doc/format.rst -.. _SciPy: http://www.scipy.org -.. _numpy-discussion list: http://scipy.org/scipylib/mailing-lists.html -.. _Sphinx: http://sphinx.pocoo.org +.. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html |