==================================== A Guide to NumPy/SciPy Documentation ==================================== .. Contents:: .. Note:: For an accompanying example, see `example.py `_. Overview -------- In general, we follow the standard Python style conventions as described here: * `Style Guide for C Code `_ * `Style Guide for Python Code `_ * `Docstring Conventions `_ Additional PEPs of interest regarding documentation of code: * `Docstring Processing Framework `_ * `Docutils Design Specification `_ Use a code checker: * `pylint `_ * `pyflakes` easy_install pyflakes * `pep8.py `_ The following import conventions are used throughout the NumPy source and documentation:: import numpy as np import scipy as sp import matplotlib as mpl import matplotlib.pyplot as plt 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 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`_, together with the epydoc output. Our docstring standard uses `re-structured text (reST) `_ syntax and is rendered using tools like epydoc_ or sphinx_ (pre-processors that understand 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 tools like epydoc_ and sphinx_ in their task. Status ------ We are busy converting existing docstrings to the new format, expanding them where they are lacking, as well as writing new ones for undocumented functions. Volunteers are welcome to join the effort on our new documentation system (see the `Documentation Editor `_ and the `Developer Zone `_). 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. **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. 3. **Parameters** Description of the function arguments, keywords and their respective types. :: Parameters ---------- x : type Description of parameter `x`. Enclose variables in single back-tics. 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:: x : {True, False} Description of `x`. 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`. 4. **Returns** Explanation of the returned values and their types, of the same format as **parameters**. 5. **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 prameters, to prevent cluttering the **parameters** section. 6. **Raises** An optional section detailing which errors get raised and under what conditions:: Raises ------ LinAlgException If the matrix is not numerically invertible. 7. **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 8. **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 `_ 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. 9. **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] 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. Follow the `citation format of the IEEE `_, which states that references are numbered, starting from one, in the order in which they are cited. 10. **Examples** An optional section for examples, using the `doctest `_ 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]) You can run most examples using:: >>> import doctest >>> doctest.testfile('example.py') or with nose:: $ nosetests --with-doctest example.py It is not necessary to use the doctest markup ```` to indicate empty lines in the output. The examples may assume that ``import numpy as np`` is executed before the example code in *numpy*, and ``import scipy as sp`` in *scipy*. Additional examples may make use of *matplotlib* for plotting, but should import it explicitly, e.g., ``import matplotlib.pyplot as plt``. 11. **Indexing tags*** Each function needs to be categorised for indexing purposes. Use the ``index`` directive:: .. index:: :refguide: ufunc, trigonometry To index a function as a sub-category of a class, separate index entries by a colon, e.g. :: :refguide: ufunc, numpy:reshape, other A `list of available categories `_ is available. Documenting classes ------------------- Class docstring ``````````````` Use the same sections as outlined above (all except ``Returns`` are applicable). The constructor (``__init__``) should also be documented here. An ``Attributes`` section may be used to describe class variables:: Attributes ---------- 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. """ 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. 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 ``courier`` if needed in any explanations (but not for variable names and doctest code or multi-line code). Variable, module and class names should be written between single backticks (```numpy```). A more extensive example of reST markup can be found in `this example document `_; the `quick reference `_ is useful while editing. Line spacing and indentation are significant and should be carefully followed. Conclusion ---------- `An example `_ of the format shown here is available. Refer to `How to Build API/Reference Documentation `_ on how to use epydoc_ or sphinx_ to construct a manual and web page. This document itself was written in ReStructuredText, and may be converted to HTML using:: $ rst2html HOWTO_DOCUMENT.txt HOWTO_DOCUMENT.html .. _SciPy: http://www.scipy.org .. _numpy-discussion list: http://www.scipy.org/Mailing_Lists .. _epydoc: http://epydoc.sourceforge.net/ .. _sphinx: http://sphinx.pocoo.org