Navigation

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.

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.

Good docstrings are very important. Unfortunately, Python itself only provides
a rather loose standard for docstrings (PEP 257), 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.