|
|
.. _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>`_
|
|
|
|
