Small doc updates.

docs/source/development/doc_guide.txt

@@ -1,8 +1,11
+.. _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
@@ -12,31 +15,32 documentation in this location will serve as the main source for IPython
 documentation and all existing documentation should be converted to this
 format.
 
-In the future, the text files in the ``docs`` directory will be used to
-generate all forms of documentation for IPython. This include documentation on
-the IPython website as well as *pdf* documentation.
+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/
 
-A bit of shell code:
 
-.. code-block:: bash
+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.
 
-    cd /tmp
-    echo "My home directory is: $HOME"
-    ls
+.. __: http://matplotlib.sourceforge.net/doc/html/devel/documenting_mpl.html
 
-A bit of Python code:
 
-.. code-block:: python
+A bit of Python code::
 
     for i in range(10):
         print i,
     print "A big number:",2**34
 
-An interactive Python session:
-
-.. code-block:: python
+An interactive Python session::
 
     >>> from IPython import genutils
     >>> genutils.get_ipython_dir()
@@ -47,15 +51,27 An IPython session:
 
 .. code-block:: ipython
 
-  In [8]: import IPython
+  In [7]: import IPython
 
-  In [9]: print "This IPython is version:",IPython.__version__
+  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