More doc updates.

- Better use of highlighting directives.
- More work on dev guide.

docs/source/development/coding_guide.txt

@@ -0,0 +1,141 b''
+==============
+ Coding guide
+==============
+
+
+Coding conventions
+==================
+
+In general, we'll try to follow the standard Python style conventions as
+described in Python's `PEP 8`_, the official Python Style Guide.
+
+.. _PEP 8: http://www.python.org/peps/pep-0008.html
+
+Other comments:
+
+- In a large file, top level classes and functions should be separated by 2-3
+  lines to make it easier to separate them visually.
+
+- Use 4 spaces for indentation, *never* use hard tabs.
+
+- Keep the ordering of methods the same in classes that have the same methods.
+  This is particularly true for classes that implement similar interfaces and
+  for interfaces that are similar.
+
+Naming conventions
+------------------
+
+In terms of naming conventions, we'll follow the guidelines of PEP 8.  Some of
+the existing code doesn't honor this perfectly, but for all new IPython code
+(and much existing code is being refactored), we'll use:
+
+- All ``lowercase`` module names.
+
+- ``CamelCase`` for class names.
+
+- ``lowercase_with_underscores`` for methods, functions, variables and
+  attributes.
+
+This may be confusing as some of the existing codebase uses a different
+convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will
+move IPython over to the new convention, providing shadow names for backward
+compatibility in public interfaces.
+
+There are, however, some important exceptions to these rules.  In some cases,
+IPython code will interface with packages (Twisted, Wx, Qt) that use other
+conventions.  At some level this makes it impossible to adhere to our own
+standards at all times.  In particular, when subclassing classes that use other
+naming conventions, you must follow their naming conventions.  To deal with
+cases like this, we propose the following policy:
+
+- If you are subclassing a class that uses different conventions, use its
+  naming conventions throughout your subclass.  Thus, if you are creating a
+  Twisted Protocol class, used Twisted's
+  ``namingSchemeForMethodsAndAttributes.``
+
+- All IPython's official interfaces should use our conventions.  In some cases
+  this will mean that you need to provide shadow names (first implement
+  ``fooBar`` and then ``foo_bar = fooBar``).  We want to avoid this at all
+  costs, but it will probably be necessary at times.  But, please use this
+  sparingly!
+
+Implementation-specific *private* methods will use
+``_single_underscore_prefix``.  Names with a leading double underscore will
+*only* be used in special cases, as they makes subclassing difficult (such
+names are not easily seen by child classes).
+
+Occasionally some run-in lowercase names are used, but mostly for very short
+names or where we are implementing methods very similar to existing ones in a
+base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
+established precedent).
+
+The old IPython codebase has a big mix of classes and modules prefixed with an
+explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
+upon, as namespaces offer cleaner prefixing. The only case where this approach
+is justified is for classes which are expected to be imported into external
+namespaces and a very generic name (like Shell) is too likely to clash with
+something else.  We'll need to revisit this issue as we clean up and refactor
+the code, but in general we should remove as many unnecessary ``IP``/``ip``
+prefixes as possible. However, if a prefix seems absolutely necessary the more
+specific ``IPY`` or ``ipy`` are preferred.
+
+
+.. _devel-testing:
+
+Testing system
+==============
+
+It is extremely important that all code contributed to IPython has tests. Tests
+should be written as unittests, doctests or as entities that the `Nose`_
+testing package will find. Regardless of how the tests are written, we will use
+`Nose`_ for discovering and running the tests. `Nose`_ will be required to run
+the IPython test suite, but will not be required to simply use IPython.
+
+.. _Nose: http://code.google.com/p/python-nose/
+
+Tests of `Twisted`__ using code should be written by subclassing the
+``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
+done, `Nose`_ will be able to run the tests and the twisted reactor will be
+handled correctly.
+
+.. __: http://www.twistedmatrix.com
+
+Each subpackage in IPython should have its own ``tests`` directory that
+contains all of the tests for that subpackage. This allows each subpackage to
+be self-contained. If a subpackage has any dependencies beyond the Python
+standard library, the tests for that subpackage should be skipped if the
+dependencies are not found. This is very important so users don't get tests
+failing simply because they don't have dependencies.
+
+We also need to look into use Noses ability to tag tests to allow a more
+modular approach of running tests.
+
+.. _devel-config:
+
+Configuration system
+====================
+
+IPython uses `.ini`_ files for configuration purposes. This represents a huge
+improvement over the configuration system used in IPython. IPython works with
+these files using the `ConfigObj`_ package, which IPython includes as
+``ipython1/external/configobj.py``.
+
+Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
+IPython should contain a ``config`` subdirectory that contains all of the
+configuration information for the subpackage. To see how configuration
+information is defined (along with defaults) see at the examples in
+``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
+the configuration information is used, see examples in
+``ipython1/kernel/scripts/ipengine.py``.
+
+Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
+are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
+validation model.  We won't actually use `Traits`_, but will implement
+something similar in pure Python.  But, even in this new system, we will still
+use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
+are interested in working on this part of IPython. The current prototype of
+``tconfig`` is located in the IPython sandbox.
+
+.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
+.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
+.. _Traits: http://code.enthought.com/traits/

docs/source/development/doc_guide.txt

@@ -0,0 +1,76 b''
+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.
+
+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.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+A bit of shell code:
+
+.. code-block:: bash
+
+    cd /tmp
+    echo "My home directory is: $HOME"
+    ls
+
+A bit of Python code:
+
+.. code-block:: python
+
+    for i in range(10):
+        print i,
+    print "A big number:",2**34
+
+An interactive Python session:
+
+.. code-block:: python
+
+    >>> from IPython import genutils
+    >>> genutils.get_ipython_dir()
+    '/home/fperez/.ipython'
+
+
+An IPython session:
+
+.. code-block:: ipython
+
+  In [8]: import IPython
+
+  In [9]: print "This IPython is version:",IPython.__version__
+  This IPython is version: 0.9.1
+
+
+
+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>`_

docs/source/development/index.txt

@@ -1,10 +1,13 b''
-==================
-Development
-==================
+===========================
+ IPython Developer's Guide
+===========================
 
 .. toctree::
    :maxdepth: 2
 
-   development.txt
+   overview.txt
+   coding_guide.txt
+   doc_guide.txt
    roadmap.txt
+
    notification_blueprint.txt

docs/source/development/overview.txt

@@ -1,16 +1,16 b''
+.. This file has a lot of bash but little python, set default role
+
+.. highlight:: bash
+
 .. _development:
 
 ==============================
-IPython development guidelines
+ IPython development overview
 ==============================
 
-
-Overview
-========
-
 Currently, IPython's development tree contains all of the code that used to be
 part of IPython since the project's inception in 2001, plus all of the effort
-that was known for a while (roughly 2004-2008) as `IPython1'.  The IPyhton1
+that was known for a while (roughly 2004-2008) as ``IPython1``.  The IPyhton1
 development was meant to be an effort to:
 
 1. Clean up the existing codebase and write lots of tests.
@@ -23,8 +23,13 b' development was meant to be an effort to:'
 While the third goal may seem a bit unrelated to the main focus of IPython, it
 turns out that the technologies required for this goal are nearly identical
 with those required for goal two. This is the main reason the interactive
-parallel computing capabilities are being put into IPython proper. Currently
-the third of these goals is furthest along.
+parallel computing capabilities are being put into IPython proper.
+
+In the summer of 2008, the IPython1 code was merged back into the mainline, and
+now there is a unified codebase.  While the above goals aren't completely
+implemented for the older code, we do have a proper :ref:`testing system
+<devel-testing>` in place (though this is still evolving), unified
+documentation and partial implementations of the more separated components.
 
 This document describes IPython from the perspective of developers.  
 
@@ -44,12 +49,14 b' subpackages will have its own:'
   
 - **Tests**.  Each subpackage shoud have its own ``tests`` subdirectory that
   contains all of the tests for that package.  For information about writing
-  tests for IPython, see the `Testing System`_ section of this document.
+  tests for IPython, see the :ref:`Testing System <devel-testing>` section of
+  this document.
   
 - **Configuration**.  Each subpackage should have its own ``config``
   subdirectory that contains the configuration information for the components
   of the subpackage.  For information about how the IPython configuration
-  system works, see the `Configuration System`_ section of this document.
+  system works, see the :ref:`Configuration System <devel-config>` section of
+  this document.
   
 - **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory
   that contains all of the command line scripts associated with the subpackage.
@@ -116,15 +123,12 b' Specific subpackages'
     today 's IPython.  Other frontends will likely be more powerful and based
     on GUI toolkits.
 
-``notebook``
-    An application that allows users to work with IPython notebooks.
-
 ``tools``
     This is where general utilities go.
 
 
-Version control
-===============
+Version control workflow
+========================
 
 All IPython development today is done using the `Bazaar`__ system for
 distributed version control and the `Launchpad`__ site for code hosting and bug
@@ -140,9 +144,7 b" for IPython you'll eventually want to have a Launchpad account (free) so you"
 can publish your own code on the site for review and merging, but small
 contributions can be simply sent via email to the IPython list as patches.
 
-Start by creating what Bazaar calls a `shared repository`_:
-
-.. sourcecode:: bash
+Start by creating what Bazaar calls a `shared repository`_::
 
     # You can choose any name you want instead of "ipython-repo"
     bzr init-repo ipython-repo
@@ -152,9 +154,7 b' Start by creating what Bazaar calls a `shared repository`_:'
 This creates an empty repository where a lot of related branches can be kept,
 and they all reuse common storage.  This way, many operations are very fast and
 take up less space.  Now, go to the newly created repository and make a local
-branch of the public trunk:
-
-.. sourcecode:: bash
+branch of the public trunk::
 
     cd ipython-repo
     # This makes a local copy of the public trunk called "trunk-lp"
@@ -162,9 +162,7 b' branch of the public trunk:'
 
 The ``trunk-lp`` branch is meant to always be a pristine copy of the public
 trunk.  From here, make a personal development copy of the public trunk, where
-you'll make your changes:
-
-.. sourcecode:: bash
+you'll make your changes::
 
     bzr branch trunk-lp trunk-dev
 
@@ -180,9 +178,7 b' is to make branches to contain specific feature implementations until they are'
 ready to be merged).
     
 The typical work cycle will be to make changes in ``trunk-dev`` and then commit
-those changes as often as needed:
-
-.. sourcecode:: bash
+those changes as often as needed::
 
     cd trunk-dev
     # ... implement cool new feature...
@@ -207,17 +203,13 b' atomic change, the bzr log should give an excellent view of the project, and'
 the ``--short`` log option becomes a nice summary.
 
 As you work on the branch, it's a good idea to frequently keep your copy of the
-trunk updated with respect to Launchpad.  This is done via:
-
-.. sourcecode:: bash
+trunk updated with respect to Launchpad.  This is done via::
 
     cd trunk-lp
     bzr pull
 
 Bazaar can then merge any changes that were done to the public trunk into your
-local branch via:
-
-.. sourcecode:: bash
+local branch via::
 
     cd trunk-dev
     bzr merge ../trunk-lp
@@ -227,16 +219,13 b' This workflow ensures that a local copy stays in sync with the public trunk,'
 while allowing for local development to be pushed back for public review.
 
 Once your changes are ready for review, you can push them to Launchpad where
-the IPython team can review them and give you feedback.  The first time, use:
+the IPython team can review them and give you feedback.  The first time, use::
 
-.. sourcecode:: bash
-
-    bzr push --remember bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
+    bzr push --remember \
+    bzr+ssh://<you>@bazaar.launchpad.net/~<you>/ipython/trunk-dev
 
 where ``<you>`` is your Launchpad user name. This will make this branch
-publicly visible to all.  In subsequent uses you can simply run in the branch:
-
-.. sourcecode:: bash
+publicly visible to all.  In subsequent uses you can simply run in the branch::
 
     bzr push
 
@@ -249,10 +238,10 b' publicly visible to all. In subsequent uses you can simply run in the branch:'
     on how to upload your keys.
     
 Once the branch is publicly visible, using the launchpad interface it can be
-marked for merging with the link ``Propose for merging into another branch``,
-leaving the default choice of trunk as its target.  This way, Launchpad tracks
-what changes of this branch are new with respect to the trunk, others in the
-team can review it, and merge the changes into the trunk.
+marked for merging with the link marked *"Propose for merging into another
+branch"*, leaving the default choice of trunk as its target.  This way,
+Launchpad tracks what changes of this branch are new with respect to the trunk,
+others in the team can review it, and merge the changes into the trunk.
 
 The IPython team has a policy of reviewing all code (both from core members of
 the team and from external contributors) before merging it.  Code should be
@@ -262,226 +251,6 b" contribution to the project, and we've found that peer review of code is an"
 excellent way to improve the quality of everyone's work.
 
 
-Coding conventions
-==================
-
-General
--------
-
-In general, we'll try to follow the standard Python style conventions as
-described here:
-
-- `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
-
-
-Other comments:
-
-- In a large file, top level classes and functions should be 
-  separated by 2-3 lines to make it easier to separate them visually.
-- Use 4 spaces for indentation.
-- Keep the ordering of methods the same in classes that have the same 
-  methods.  This is particularly true for classes that implement 
-  similar interfaces and for interfaces that are similar.
-
-Naming conventions
-------------------
-
-In terms of naming conventions, we'll follow the guidelines from the `Style
-Guide for Python Code`_.
-
-For all new IPython code (and much existing code is being refactored), we'll use:
-
-- All ``lowercase`` module names.
-
-- ``CamelCase`` for class names.
-
-- ``lowercase_with_underscores`` for methods, functions, variables and
-  attributes.
-
-This may be confusing as most of the existing IPython codebase uses a different
-convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will
-move IPython over to the new convention, providing shadow names for backward
-compatibility in public interfaces.
-
-There are, however, some important exceptions to these rules.  In some cases,
-IPython code will interface with packages (Twisted, Wx, Qt) that use other
-conventions.  At some level this makes it impossible to adhere to our own
-standards at all times.  In particular, when subclassing classes that use other
-naming conventions, you must follow their naming conventions.  To deal with
-cases like this, we propose the following policy:
-
-- If you are subclassing a class that uses different conventions, use its
-  naming conventions throughout your subclass.  Thus, if you are creating a
-  Twisted Protocol class, used Twisted's
-  ``namingSchemeForMethodsAndAttributes.``
-
-- All IPython's official interfaces should use our conventions.  In some cases
-  this will mean that you need to provide shadow names (first implement
-  ``fooBar`` and then ``foo_bar = fooBar``).  We want to avoid this at all
-  costs, but it will probably be necessary at times.  But, please use this
-  sparingly!
-
-Implementation-specific *private* methods will use
-``_single_underscore_prefix``.  Names with a leading double underscore will
-*only* be used in special cases, as they makes subclassing difficult (such
-names are not easily seen by child classes).
-
-Occasionally some run-in lowercase names are used, but mostly for very short
-names or where we are implementing methods very similar to existing ones in a
-base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
-established precedent).
-
-The old IPython codebase has a big mix of classes and modules prefixed with an
-explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
-upon, as namespaces offer cleaner prefixing. The only case where this approach
-is justified is for classes which are expected to be imported into external
-namespaces and a very generic name (like Shell) is too likely to clash with
-something else. We'll need to revisit this issue as we clean up and refactor
-the code, but in general we should remove as many unnecessary ``IP``/``ip``
-prefixes as possible. However, if a prefix seems absolutely necessary the more
-specific ``IPY`` or ``ipy`` are preferred.
-
-
-Documentation
-=============
-
-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.
-
-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.
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-
-A bit of shell code:
-
-.. sourcecode:: bash
-
-    cd /tmp
-    echo "My home directory is: $HOME"
-    ls
-
-A bit of Python code:
-
-.. sourcecode:: python
-
-    for i in range(10):
-        print i,
-    print "A big number:",2**34
-
-An interactive Python session:
-
-.. sourcecode:: python
-
-    >>> from IPython import genutils
-    >>> genutils.get_ipython_dir()
-    '/home/fperez/.ipython'
-
-
-An IPython session:
-
-.. sourcecode:: ipython
-
-  In [8]: import IPython
-
-  In [9]: print "This IPython is version:",IPython.__version__
-  This IPython is version: 0.9.1
-
-
-
-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>`_
-
-
-
-.. _devel_testing:
-
-Testing system
-==============
-
-It is extremely important that all code contributed to IPython has tests. Tests
-should be written as unittests, doctests or as entities that the `Nose`_
-testing package will find. Regardless of how the tests are written, we will use
-`Nose`_ for discovering and running the tests. `Nose`_ will be required to run
-the IPython test suite, but will not be required to simply use IPython.
-
-.. _Nose: http://code.google.com/p/python-nose/
-
-Tests of `Twisted`__ using code should be written by subclassing the
-``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
-done, `Nose`_ will be able to run the tests and the twisted reactor will be
-handled correctly.
-
-.. __: http://www.twistedmatrix.com
-
-Each subpackage in IPython should have its own ``tests`` directory that
-contains all of the tests for that subpackage. This allows each subpackage to
-be self-contained. If a subpackage has any dependencies beyond the Python
-standard library, the tests for that subpackage should be skipped if the
-dependencies are not found. This is very important so users don't get tests
-failing simply because they don't have dependencies.
-
-We also need to look into use Noses ability to tag tests to allow a more
-modular approach of running tests.
-
-.. _devel_config:
-
-Configuration system
-====================
-
-IPython uses `.ini`_ files for configuration purposes. This represents a huge
-improvement over the configuration system used in IPython. IPython works with
-these files using the `ConfigObj`_ package, which IPython includes as
-``ipython1/external/configobj.py``.
-
-Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
-IPython should contain a ``config`` subdirectory that contains all of the
-configuration information for the subpackage. To see how configuration
-information is defined (along with defaults) see at the examples in
-``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
-the configuration information is used, see examples in
-``ipython1/kernel/scripts/ipengine.py``.
-
-Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
-are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
-validation model.  We won't actually use `Traits`_, but will implement
-something similar in pure Python.  But, even in this new system, we will still
-use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
-are interested in working on this part of IPython. The current prototype of
-``tconfig`` is located in the IPython sandbox.
-
-.. _.ini: http://docs.python.org/lib/module-ConfigParser.html
-.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
-.. _Traits: http://code.enthought.com/traits/
-
-
 Installation and testing scenarios
 ==================================
 
@@ -489,43 +258,54 b' This section outlines the various scenarios that we need to test before we'
 release an IPython version.  These scenarios represent different ways of
 installing IPython and its dependencies.
 
+
 Installation scenarios under Linux and OS X
 -------------------------------------------
 
-    1.  Install from tarball using ``python setup.py install``.
-        a.  With only readline+nose dependencies installed.
-        b.  With all dependencies installed (readline, zope.interface, Twisted,
-        foolscap, Sphinx, nose, pyOpenSSL).
-	    
-    2.  Install using easy_install.
+1.  Install from tarball using ``python setup.py install``.
+
+  * With only readline+nose dependencies installed.
+
+  * With all dependencies installed (readline, zope.interface, Twisted,
+    foolscap, Sphinx, nose, pyOpenSSL).
+
+2.  Install using easy_install.
+
+  * With only readline+nose dependencies installed.
+    
+    * Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
 
-        a.  With only readline+nose dependencies installed.
-            i.  Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
-            ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
+    * Optional dependency sets:
+      ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
 
-        b.  With all dependencies already installed.
+  * With all dependencies already installed.
 	
 
 Installation scenarios under Win32
 ----------------------------------
 
-	1.  Install everything from .exe installers
-	2.  easy_install?
+#. Install everything from .exe installers
+#. easy_install?
 
 
 Tests to run for these scenarios
 --------------------------------
 
-    1.  Run the full test suite.
-    2.  Start a controller and engines and try a few things by hand.
-        a.  Using ipcluster.
-        b.  Using ipcontroller/ipengine by hand.
+#. Run the full test suite.
+
+#. Start a controller and engines and try a few things by hand.
+
+   * Using ipcluster.
+   * Using ipcontroller/ipengine by hand.
+
+#. Run a few of the parallel examples.
+
+#. Try the kernel with and without security with and without PyOpenSSL
+   installed.
+
+#. Beat on the IPython terminal a bunch.
 
-    3.  Run a few of the parallel examples.
-    4.  Try the kernel with and without security with and without PyOpenSSL
-        installed.
-    5.  Beat on the IPython terminal a bunch.
-    6.  Make sure that furl files are being put in proper locations.
+#. Make sure that furl files are being put in proper locations.
 
 
 Release checklist

docs/source/install/install.txt

@@ -1,3 +1,7 b''
+.. There's little Python in this file, so make the default language bash.
+
+.. highlight:: bash
+
 Overview
 ========
 
@@ -42,31 +46,25 b' Installation using easy_install'
 -------------------------------
 
 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
-to use :command:`easy_install`:
-
-.. sourcecode:: bash
+to use :command:`easy_install`::
 
     easy_install IPython
 
-Unless you've written a custom distutils script as explained here_, that will
+Unless you've written a custom distutils script as explained `here`__, that will
 try to install either in a default system-wide location, which may require
 administrator access.  If that is the case, you can either run the command with
-root privileges:
-
-.. sourcecode:: bash
+root privileges::
 
     sudo easy_install IPython
 
-or you can specify an alternate location, for example:
-
-.. sourcecode:: bash
+or you can specify an alternate location, for example::
 
     easy_install --prefix=~/usr/local IPython
 
 where this assumes that ``~/usr/local`` is a valid prefix for you to install
 packages to in your user account.
 
-.. _here: http://docs.python.org/install/index.html#inst-config-files
+.. __: http://docs.python.org/install/index.html#inst-config-files
 
 
 Installation from source
@@ -75,9 +73,7 b' Installation from source'
 If you don't want to use :command:`easy_install`, or don't have it installed,
 just grab the latest stable build of IPython from `here
 <http://ipython.scipy.org/dist/>`_.  Then do the following (using the
-appropriate version number):
-
-.. sourcecode:: bash
+appropriate version number)::
 
     tar -xzf ipython.tar.gz
     cd ipython
@@ -91,11 +87,13 b' Windows'
 
 There are a few caveats for Windows users.  The main issue is that a basic ``python setup.py install`` approach won't create ``.bat`` file or Start Menu shortcuts, which most users want.  To get an installation with these, there are two choices:
 
-1.  Install using :command:`easy_install`.
+#. Install using :command:`easy_install`.
 
-2.  Install using our binary ``.exe`` Windows installer, which can be found at `here <http://ipython.scipy.org/dist/>`_
+#. Install using our binary ``.exe`` Windows installer, which can be found at
+`here <http://ipython.scipy.org/dist/>`_
 
-3.  Install from source, but using :mod:`setuptools` (``python setupegg.py install``).
+#. Install from source, but using :mod:`setuptools` (``python setupegg.py
+   install``).
 
 Installing the development version
 ----------------------------------
@@ -104,8 +102,6 b' It is also possible to install the development version of IPython from our'
 `Bazaar <http://bazaar-vcs.org/>`_ source code repository.  To do this you will
 need to have Bazaar installed on your system.  Then just do::
 
-    .. sourcecode:: bash
-
     bzr branch lp:ipython
     cd ipython
     python setup.py install
@@ -114,18 +110,17 b" Again, this last step on Windows won't create ``.bat`` files or Start Menu short"
 
 Some users want to be able to follow the development branch as it changes.  If
 you have :mod:`setuptools` installed, this is easy. Simply replace the last
-step by:
-
-.. sourcecode:: bash
+step by::
 
     python setupegg.py develop
 
-This creates links in the right places and installs the command line script to the appropriate places.  Then, if you want to update your IPython at any time, just do:
-
-.. sourcecode:: bash
+This creates links in the right places and installs the command line script to
+the appropriate places.  Then, if you want to update your IPython at any time,
+just do::
 
     bzr pull
 
+    
 Basic optional dependencies
 ===========================
 
@@ -140,7 +135,9 b' If you are comfortable installing these things yourself, have at it, otherwise r'
 readline
 --------
 
-In principle, all Python distributions should come with a working :mod:`readline` module.  But, reality is not quite that simple.  There are two common situations where you won't have a working :mod:`readline` module:
+In principle, all Python distributions should come with a working
+:mod:`readline` module.  But, reality is not quite that simple.  There are two
+common situations where you won't have a working :mod:`readline` module:
 
 * If you are using the built-in Python on Mac OS X.
 
@@ -153,9 +150,7 b' many of the issues related to the differences between readline and libedit have'
 been resolved.  For many users, libedit may be sufficient.
 
 Most users on OS X will want to get the full :mod:`readline` module.  To get a
-working :mod:`readline` module, just do (with :mod:`setuptools` installed):
-
-.. sourcecode:: bash
+working :mod:`readline` module, just do (with :mod:`setuptools` installed)::
 
     easy_install readline
 
@@ -181,23 +176,17 b' nose'
 
 To run the IPython test suite you will need the :mod:`nose` package.  Nose
 provides a great way of sniffing out and running all of the IPython tests.  The
-simplest way of getting nose, is to use :command:`easy_install`:
-
-.. sourcecode:: bash
+simplest way of getting nose, is to use :command:`easy_install`::
 
     easy_install nose
 
-Another way of getting this is to do:
-
-.. sourcecode:: bash
+Another way of getting this is to do::
 
     easy_install IPython[test]
 
 For more installation options, see the `nose website
 <http://somethingaboutorange.com/mrl/projects/nose/>`_.  Once you have nose
-installed, you can run IPython's test suite using the iptest command:
-
-.. sourcecode:: bash
+installed, you can run IPython's test suite using the iptest command::
 
     iptest
 
@@ -206,9 +195,7 b' pexpect'
 -------
 
 The `pexpect <http://www.noah.org/wiki/Pexpect>`_ package is used in IPython's
-:command:`irunner` script.  On Unix platforms (including OS X), just do:
-
-.. sourcecode:: bash
+:command:`irunner` script.  On Unix platforms (including OS X), just do::
 
     easy_install pexpect
 
@@ -227,9 +214,7 b' features require a number of additional packages:'
 * pyOpenSSL (security for network connections)
 
 On a Unix style platform (including OS X), if you want to use
-:mod:`setuptools`, you can just do:
-
-.. sourcecode:: bash
+:mod:`setuptools`, you can just do::
 
     easy_install IPython[kernel]    # the first three
     easy_install IPython[security]  # pyOpenSSL
@@ -238,9 +223,7 b' zope.interface and Twisted'
 --------------------------
 
 On Unix style platforms (including OS X), the simplest way of getting the these
-is to use :command:`easy_install`:
-
-.. sourcecode:: bash
+is to use :command:`easy_install`::
 
     easy_install zope.interface
     easy_install Twisted
@@ -260,9 +243,7 b' Foolscap'
 Foolscap uses Twisted to provide a very nice secure RPC protocol that we use to
 implement our parallel computing features.
 
-On all platforms a simple:
-
-.. sourcecode:: bash
+On all platforms a simple::
 
     easy_install foolscap
 
@@ -297,4 +278,4 b' a nice wxPython based IPython GUI. As you would expect, this GUI requires'
 wxPython.  Most Linux distributions have wxPython packages available and the
 built-in Python on OS X comes with wxPython preinstalled.  For Windows, a
 binary installer is available on the `wxPython website
-<http://www.wxpython.org/>`_.
  No newline at end of file
+<http://www.wxpython.org/>`_.