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.
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:
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:
cd /tmp
echo "My home directory is: $HOME"
ls
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.
The NumPy documentation guidelines contain detailed information on this standard, and for a quick overview, the NumPy example docstring is a useful read.
As in the past IPython used epydoc, currently many docstrings still use epydoc conventions. We will update them as we go, but all new code should be fully documented using the NumPy standard.
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):