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`_ for markup and formatting. All such documentation
should be placed in the top level directory ``docs`` 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 and all existing documentation should be converted to this
format.

The actual HTML and PDF docs are built using the Sphinx_ documentation
generation tool.  Sphinx has been adopted as the default documentation tool for
Python itself as of version 2.6, as well as by a number of projects that
IPython is related with, such as numpy, scipy, matplotlib, sage and nipy.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org/


The rest of this document is mostly taken from the `matploblib
documentation`__; 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 guide.  What follows is thus a lightly adapted
version of the matplotlib documentation guide, taken with permission from the
MPL team.

.. __: http://matplotlib.sourceforge.net/doc/html/devel/documenting_mpl.html


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. All new code will use `Epydoc`_ for
generating API docs, so we will follow the `Epydoc`_ conventions. More
specifically, we will use `reStructuredText`_ for markup and formatting, since
it is understood by a wide variety of tools. This means that if in the future
we have any reason to change from `Epydoc`_ to something else, we'll have fewer
transition pains.

Details about using `reStructuredText`_ for docstrings can be found `here
<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.

.. _Epydoc: http://epydoc.sourceforge.net/

Additional PEPs of interest regarding documentation of code:

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