diff options
Diffstat (limited to 'doc/HOWTO_DOCUMENT.txt')
| -rw-r--r-- | doc/HOWTO_DOCUMENT.txt | 430 |
1 files changed, 430 insertions, 0 deletions
diff --git a/doc/HOWTO_DOCUMENT.txt b/doc/HOWTO_DOCUMENT.txt new file mode 100644 index 000000000..03c35283d --- /dev/null +++ b/doc/HOWTO_DOCUMENT.txt @@ -0,0 +1,430 @@ +==================================== +A Guide to NumPy/SciPy Documentation +==================================== + +.. Contents:: + +.. Note:: + + For an accompanying example, see `example.py + <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`_. + +Overview +-------- +In general, we follow the standard Python style conventions as described here: + * `Style Guide for C Code <http://www.python.org/peps/pep-0007.html>`_ + * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_ + * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_ + +Additional PEPs of interest regarding documentation of code: + * `Docstring Processing Framework <http://www.python.org/peps/pep-0256.html>`_ + * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_ + +Use a code checker: + * `pylint <http://www.logilab.org/857>`_ + * `pyflakes` easy_install pyflakes + * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/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) +<http://docutils.sourceforge.net/rst.html>`_ 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 `Developer Zone +<http://www.scipy.org/Developer_Zone/DocMarathon2008>`_). + +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`. + +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:: + + 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 <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. + +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 + <http://www.ieee.org/pubs/transactions/auinfo03.pdf>`_, 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 + <http://www.python.org/doc/lib/module-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. You can + run these examples by doing:: + + >>> import doctest + >>> doctest.testfile('example.py') + + or, using nose, + + :: + + $ nosetests --with-doctest example.py + + Blank lines are used to seperate doctests. When they occur in the + expected output, they should be replaced by ``<BLANKLINE>`` (see + `doctest options + <http://docs.python.org/lib/doctest-options.html>`_ for other such + special strings), e.g. + + :: + + >>> print "a\n\nb" + a + <BLANKLINE> + b + + 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 + <http://www.scipy.org/Developer_Zone/ReferenceGuide>`_ 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 <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 +---------- + +`An example +<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`_ of the +format shown here is available. Refer to `How to Build API/Reference +Documentation +<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_BUILD_DOCS.txt>`_ +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 |