Updated dev doc guide for sphinx/numpy doc standard instead of the outdated

epydoc information.

docs/source/development/doc_guide.txt

@@ -1,92 +1,103 b''
 .. _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
+.. __: http://matplotlib.sourceforge.net/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.
+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.
 
-Details about using `reStructuredText`_ for docstrings can be found `here
-<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+.. _PEP 257: http://www.python.org/peps/pep-0257.html
+.. _NumPy documentation guidelines: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
 
-.. _Epydoc: http://epydoc.sourceforge.net/
+.. _example docstring: http://projects.scipy.org/numpy/browser/trunk/doc/EXAMPLE_DOCSTRING.txt
 
-Additional PEPs of interest regarding documentation of code:
+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 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>`_