==================================== A Guide to NumPy/SciPy Documentation ==================================== .. Contents:: .. Attention:: This document is slightly out of date. During the December 2007 sprint, Travis Oliphant made some changes to the NumPy/SciPy docstring standard. The changes are relatively minor, but the standard no longer follows the epydoc/restructured text standards. The changes brings our docstring standard more in line with the ETS standard; in addition, it also conserves horizontal real-estate and arguably looks better when printed as plain text. Unfortunately, these changes mean that currently it isn't possible to render the docstrings as desired. Travis has committed to writing something to render the docstrings. At that point, we will update this document to correspond with the new standard. For now, just refer to: `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 `__ Common import standards:: import numpy as np import scipy as sp 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. It is highly desireable that both NumPy and SciPy_ and scikits to follow a common convention for docstrings that provide for consistency while also allowing epydoc_ to produce nicely-formatted reference guides. This document describes the current community consensus for this standard. If you have suggestions for improvements, post them on the `numpy-discussion list`_, together with the epydoc output. Our docstring standard uses `reST `__ syntax and is rendered using something like epydoc_ (+ a pre-processor which understands the particular documentation style we are using). The markup in this proposal is as basic as possible which still looks reasonable when the text is just printed. In particular, it avoids too much cruft in the reST syntax and other epydoc_-isms. The guiding principle is that human readers of the text itself are given precedence over contorting the docstring so that epydoc_ produces nice output. In order to improve the rendered output we should work on making pre-processor tools to assist epydoc_ or another similar tool, rather than making human readers conform to a particular computer-imposed style. Status ------ We are currently trying to convert existing docstrings to the new format and write them for those that currently lack docstrings. We are also trying to improve the rendered output either using a pre-processor to epydoc or another tool similar to epydoc. Sections -------- The proposed sections of the docstring are: 1. **Short summary:** A one-line summary not using variable names or the function name (unless a C-function). 2. **Extended summary:** A few sentences giving an extended description. 3. **Parameters:** Description of the function arguments, keywords and their respective types. 4. **Returns:** Explanation of the returned values and their types. 5. **Other parameters:** An optional section used to describe little used parameters so that functions with a large number of keyword argument can still be well documented without cluttering the main parameters' list. 6. **Raises:** An optional section detailing which errors get raised under what conditions. 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. 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, possibly written in `LaTeX `__. 9. **Examples:** An optional section for examples, using the `doctest `__ format. It can provide an inline mini-tutorial as well as additional regression testing. While optional, this section is very strongly encouraged. You can run the tests by doing:: >>> import doctest >>> doctest.testfile('example.py') Blank lines are used to seperate doctests. When they occur in the expected output, they should be replaced by ```` (see `doctest options `_), e.g. :: >>> print "a\n\nb" a b Common reST concepts -------------------- For paragraphs, indentation is significant and indicates indentation in the output. New paragraphs are marked with blank line. Use *italics*, **bold**, and ``courier`` if needed in any explanations (but not for variable names and doctest code or multi-line code) Use ``:lm:`eqn``` for in-line math in latex format (remember to use the raw-format for your text string or escape any '\' symbols). Use ``:m:`eqn``` for non-latex math. A more extensive example of reST markup can be found here: http://docutils.sourceforge.net/docs/user/rst/demo.txt Line spacing and indentation are significant and should be carefully followed. Using Epydoc_ ------------- Currently, we recommend that you build epydoc from the trunk:: svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc cd epydoc/src sudo python setup.py install Since we use reST-formatted docstrings instead of the epytext markup, you will need to include the following line near the top of your module:: __docformat__ = "restructuredtext en" The appearance of some elements can be changed in the epydoc.css style sheet. Emphasized text appearance can be controlled by the definition of the tag. For instance, to make them bold, insert:: em {font-weight: bold;} The variables' types are in a span of class rst-classifier, hence can be changed by inserting something like:: span.rst-classifier {font-weight: normal;} The first line of the signature should **not** copy the signature unless the function is written in C, in which case it is mandatory. If the function signature is generic (uses ``*args`` or ``**kwds``), then a function signature may be included. Use optional in the "type" field for parameters that are non-keyword optional for C-functions. Epydoc depends on Docutils for reStructuredText parsing. You can download Docutils from the `Docutils sourceforge page. `__ You may also be able to use a package manager like yum to install a current version:: $ sudo yum install python-docutils Example ------- Here is a short example module, `plain text `__ or `rendered `__ in HTML. To try this yourself, simply download the example.py:: svn co http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Then, run epydoc:: $ epydoc example.py The output is placed in ``./html``, and may be viewed by loading the ``index.html`` file into your browser. 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/