path: root/numpy/doc/HOWTO_DOCUMENT.txt

====================================
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
  <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>`__

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

9. **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 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 ``<BLANKLINE>`` (see
   `doctest options
   <http://docs.python.org/lib/doctest-options.html>`_), e.g.

   ::

     >>> print "a\n\nb"
     a
     <BLANKLINE>
     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 <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.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/