docs/source/development/doc_guide.txt

.. _documenting-ipython:

=====================
 Documenting IPython
=====================

Standalone documentation
========================

All standalone documentation should be written in plain text (``.txt``) files
using reStructuredText [reStructuredText]_ for markup and formatting. All such
documentation should be placed in the directory :file:`docs/source` of the
IPython source tree. Or, when appropriate, a suitably named subdirectory
should be used. The documentation in this location will serve as the main
source for IPython documentation.

The actual HTML and PDF docs are built using the Sphinx [Sphinx]_
documentation generation tool. Once you have Sphinx installed, you can build
the html docs yourself by doing:

.. code-block:: bash

    $ cd ipython-mybranch/docs
    $ make html

Our usage of Sphinx follows that of matplotlib [Matplotlib]_ closely. We are
using a number of Sphinx tools and extensions written by the matplotlib team
and will mostly follow their conventions, which are nicely spelled out in
their documentation guide [MatplotlibDocGuide]_. What follows is thus a
abridged version of the matplotlib documentation guide, taken with permission
from the matplotlib team.

If you are reading this in a web browser, you can click on the "Show Source"
link to see the original reStricturedText for the following examples.

A bit of Python code::

    for i in range(10):
        print i,
    print "A big number:",2**34

An interactive Python session::

    >>> from IPython import genutils
    >>> genutils.get_ipython_dir()
    '/home/fperez/.ipython'

An IPython session:

.. code-block:: ipython

  In [7]: import IPython

  In [8]: print "This IPython is version:",IPython.__version__
  This IPython is version: 0.9.1

  In [9]: 2+4
  Out[9]: 6


A bit of shell code:

.. code-block:: bash

    cd /tmp
    echo "My home directory is: $HOME"
    ls

Docstring format
================

Good docstrings are very important.  Unfortunately, Python itself only provides
a rather loose standard for docstrings [PEP257]_, and there is no universally
accepted convention for all the different parts of a complete docstring.
However, the NumPy project has established a very reasonable standard, and has
developed some tools to support the smooth inclusion of such docstrings in
Sphinx-generated manuals.  Rather than inventing yet another pseudo-standard,
IPython will be henceforth documented using the NumPy conventions; we carry
copies of some of the NumPy support tools to remain self-contained, but share
back upstream with NumPy any improvements or fixes we may make to the tools.

The NumPy documentation guidelines [NumPyDocGuide]_ contain detailed
information on this standard, and for a quick overview, the NumPy example
docstring [NumPyExampleDocstring]_ is a useful read.

In the past IPython used epydoc so currently many docstrings still use epydoc
conventions.  We will update them as we go, but all new code should be
documented using the NumPy standard.

Here are two additional PEPs of interest regarding documentation of code.
While both of these were rejected, the ideas therein form much of the basis of
docutils (the machinery to process reStructuredText):

* `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
* `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_


.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
.. [MatplotlibDocGuide] http://matplotlib.sourceforge.net/devel/documenting_mpl.html
.. [PEP257] PEP 257.  http://www.python.org/peps/pep-0257.html
.. [NumPyDocGuide] NumPy documentation guide.  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
.. [NumPyExampleDocstring] NumPy example docstring. http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt