====================================
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 <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>`__
 * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>`__

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_ 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
<http://docutils.sourceforge.net/rst.html>`__ 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 <http://www.latex-project.org/>`__.

8. **Examples:**
   An optional section for examples, using the `doctest
   <http://www.python.org/doc/lib/module-doctest.html>`__ 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 ``<BLANKLINE>`` (see
   `doctest options
   <http://docs.python.org/lib/doctest-options.html>`_), e.g.

   ::

     >>> print "a\n\nb"
     a
     <BLANKLINE>
     b

Common reST concepts
--------------------

A reST-documented module should define::

  __docformat__ = 'restructuredtext en'

at the top level in accordance with `PEP 258
<http://www.python.org/dev/peps/pep-0258>`__.  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 <em>
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. <http://docutils.sourceforge.net/>`__
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 <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`__
or
`rendered <http://www.scipy.org/doc/example>`__ 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/
