==================================== A Guide to NumPy/SciPy Documentation ==================================== .. Contents:: 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 epydoc_. The markup in this proposal is as basic as possible and, in particular, avoids the use of epydoc consolidated fields. This is both because there are a limited number of such fields, inadequate to our current needs, and because epydoc moves the fields to the end of the documentation, messing up the ordering. Standard definition lists are used instead. Likewise, epydoc moves headings and have an unwelcome size in the default style sheet, therefore they are also avoided. Status ------ We are currently trying to: 1. Agree on docstring standards. 2. Work with Ed loper to ensure that epydoc_ provides the functionality we need. 3. Convert existing docstrings to the new format and write them for those that currently lack docstrings. 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. **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. 7. **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 `__. 8. **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 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 -------------------- A reST-documented module should define:: __docformat__ = 'restructuredtext en' at the top level in accordance with `PEP 258 `__. Note that the ``__docformat__`` variable in a package's ``__init__.py`` file does not apply to objects defined in subpackages and submodules. 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 The appearance of some elements can be changed in the epydoc.css style sheet. The list headings, i.e. *Parameters*:, are emphasized text, so their appearance is 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.txt 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/