Work on documentation.

* Reorganizing material everywhere.
* Consolidating material in config and development.  We had lots of
  repeated material in development.
* Removing or fixing outdated or incorrect material.

docs/source/development/contributing.txt

@@ -0,0 +1,191 b''
+How to contribute to IPython
+============================
+
+IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
+This makes it easy for people to contribute to the development of IPython.
+There are several ways in which you can join in.
+
+If you have a small change that you want to send to the team, you can edit your
+bazaar checkout of IPython (see below) in-place, and ask bazaar for the
+differences::
+
+    $ cd /path/to/your/copy/of/ipython
+    $ bzr diff > my_fixes.diff
+
+This produces a patch file with your fixes, which we can apply to the source
+tree.  This file should then be attached to a ticket in our `bug tracker
+<https://bugs.launchpad.net/ipython>`_, indicating what it does.
+
+This model of creating small, self-contained patches works very well and there
+are open source projects that do their entire development this way.  However,
+in IPython we have found that for tracking larger changes, making use of
+bazaar's full capabilities in conjunction with Launchpad's code hosting
+services makes for a much better experience.
+
+Making your own branch of IPython allows you to refine your changes over time,
+track the development of the main team, and propose your own full version of
+the code for others to use and review, with a minimum amount of fuss.  The next
+parts of this document will explain how to do this.
+
+Install Bazaar and create a Launchpad account
+---------------------------------------------
+
+First make sure you have installed Bazaar (see their `website
+<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
+you, try the following::
+
+    $ bzr whoami
+    Joe Coder <[e-mail]>
+
+This should display your name and email. Next, you will want to create an
+account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
+ssh keys. For more information of setting up your ssh keys, see `this link
+<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
+
+Get the main IPython branch from Launchpad
+------------------------------------------
+
+Now, you can get a copy of the main IPython development branch (we call this
+the "trunk")::
+
+    $ bzr branch lp:ipython
+
+Create a working branch
+-----------------------
+
+When working on IPython, you won't actually make edits directly to the
+:file:`lp:ipython` branch. Instead, you will create a separate branch for your
+changes. For now, let's assume you want to do your work in a branch named
+"ipython-mybranch". Create this branch by doing::
+
+    $ bzr branch ipython ipython-mybranch
+
+When you actually create a branch, you will want to give it a name that
+reflects the nature of the work that you will be doing in it, like
+"install-docs-update".
+
+Make edits in your working branch
+---------------------------------
+
+Now you are ready to actually make edits in your :file:`ipython-mybranch`
+branch. Before doing this, it is helpful to install this branch so you can
+test your changes as you work. This is easiest if you have setuptools
+installed. Then, just do::
+
+    $ cd ipython-mybranch
+    $ python setupegg.py develop
+
+Now, make some changes. After a while, you will want to commit your changes.
+This let's Bazaar know that you like the changes you have made and gives you
+an opportunity to keep a nice record of what you have done. This looks like
+this::
+
+    $ ...do work in ipython-mybranch...
+    $ bzr commit -m "the commit message goes here"
+
+Please note that since we now don't use an old-style linear ChangeLog (that
+tends to cause problems with distributed version control systems), you should
+ensure that your log messages are reasonably detailed.  Use a docstring-like
+approach in the commit messages (including the second line being left
+*blank*)::
+
+  Single line summary of  changes being committed.
+
+  * more details when warranted ...
+  * including crediting outside contributors if they sent the
+    code/bug/idea!
+
+As you work, you will repeat this edit/commit cycle many times. If you work on
+your branch for a long time, you will also want to get the latest changes from
+the :file:`lp:ipython` branch. This can be done with the following sequence of
+commands::
+
+    $ ls
+    ipython
+    ipython-mybranch
+    
+    $ cd ipython
+    $ bzr pull
+    $ cd ../ipython-mybranch
+    $ bzr merge ../ipython
+    $ bzr commit -m "Merging changes from trunk"
+
+Along the way, you should also run the IPython test suite.  You can do this
+using the :command:`iptest` command (which is basically a customized version of
+:command:`nosetests`)::
+
+    $ cd
+    $ iptest
+
+The :command:`iptest` command will also pick up and run any tests you have
+written. See :ref:`testing documentation <devel_testing>` for further details
+on the testing system.
+
+
+Post your branch and request a code review
+------------------------------------------
+
+Once you are done with your edits, you should post your branch on Launchpad so
+that other IPython developers can review the changes and help you merge your
+changes into the main development branch. To post your branch on Launchpad,
+do::
+
+    $ cd ipython-mybranch
+    $ bzr push lp:~yourusername/ipython/ipython-mybranch
+
+Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
+should see your branch under the "Code" tab. If you click on your branch, you
+can provide a short description of the branch as well as mark its status. Most
+importantly, you should click the link that reads "Propose for merging into
+another branch". What does this do?
+
+This let's the other IPython developers know that your branch is ready to be
+reviewed and merged into the main development branch. During this review
+process, other developers will give you feedback and help you get your code
+ready to be merged. What types of things will we be looking for:
+
+* All code is documented.
+* All code has tests.
+* The entire IPython test suite passes.
+
+Once your changes have been reviewed and approved, someone will merge them
+into the main development branch.
+
+
+Some notes for core developers when merging third-party contributions
+=====================================================================
+
+Core developers, who ultimately merge any approved branch (from themselves,
+another developer, or any third-party contribution) will typically use
+:command:`bzr merge` to merge the branch into the trunk and push it to the
+main Launcphad site. This is a short list of things to keep in mind when doing
+this process, so that the project history is easy to understand in the long
+run, and that generating release notes is as painless and accurate as
+possible.
+
+- When you merge any non-trivial functionality (from one small bug fix to a
+  big feature branch), please remember to always edit the :file:`changes.txt`
+  file accordingly. This file has one main section for each release, and if
+  you edit it as you go, noting what new features, bug fixes or API changes
+  you have made, the release notes will be almost finished when they are
+  needed later. This is much easier if done when you merge the work, rather
+  than weeks or months later by re-reading a massive Bazaar log.
+
+- When big merges are done, the practice of putting a summary commit message
+  in the merge is *extremely* useful. It makes this kind of job much nicer,
+  because that summary log message can be almost copy/pasted without changes,
+  if it was well written, rather than dissecting the next-level messages from
+  the individual commits.
+
+- It's important that we remember to always credit who gave us something if
+  it's not the committer. In general, we have been fairly good on this front,
+  this is just a reminder to keep things up. As a note, if you are ever
+  committing something that is completely (or almost so) a third-party
+  contribution, do the commit as::
+
+    $ bzr commit --author="Someone Else"
+
+  This way it will show that name separately in the log, which makes it even
+  easier to spot. Obviously we often rework third party contributions
+  extensively, but this is still good to keep in mind for cases when we don't
+  touch the code too much.
  No newline at end of file

docs/source/development/release.txt

@@ -0,0 +1,25 b''
+Release checklist
+=================
+
+Most of the release process is automated by the :file:`release` script in the
+:file:`tools` directory.  This is just a handy reminder for the release manager.
+
+#. First, run :file:`build_release`, which does all the file checking and
+   building that the real release script will do.  This will let you do test
+   installations, check that the build procedure runs OK, etc.  You may want to
+   disable a few things like multi-version RPM building while testing, because
+   otherwise the build takes really long.
+
+#. Run the release script, which makes the tar.gz, eggs and Win32 .exe
+   installer.  It posts them to the site and registers the release with PyPI.
+
+#. Updating the website with announcements and links to the updated
+   changes.txt in html form. Remember to put a short note both on the news
+   page of the site and on Launcphad.
+
+#. Drafting a short release announcement with i) highlights and ii) a link to
+   the html changes.txt.
+
+#. Make sure that the released version of the docs is live on the site.
+
+#. Celebrate!
  No newline at end of file

docs/source/development/testing.txt

@@ -0,0 +1,194 b''
+.. _testing:
+
+=========================
+Writing and running tests
+=========================
+
+Overview
+========
+
+It is extremely important that all code contributed to IPython has tests.
+Tests should be written as unittests, doctests or other entities that the
+IPython test system can detect.  See below for more details on this.
+
+Each subpackage in IPython should have its own :file:`tests` directory that
+contains all of the tests for that subpackage. All of the files in the
+:file:`tests` directory should have the word "tests" in them to enable
+the testing framework to find them.  
+
+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 are still figuring out the best way for this
+to be handled.
+
+Status
+======
+
+Currently IPython's testing system is being reworked.  In the meantime,
+we recommend the following testing practices:
+
+* To run regular tests, use the :cmd:`nosetests` command on a per file basis:
+
+.. code-block:: bash
+
+    nosetests -vvs IPython.core.tests.test_component
+
+* To run Twisted-using tests, use the :cmd:`trial` command on a per file 
+  basis:
+
+.. code-block:: bash
+
+    trial IPython.kernel
+
+* For now, regular tests (of non-Twisted using code) should be written as
+  unit tests.  They should be subclasses of :class:`unittest.TestCase`.
+
+* Tests of Twisted [Twisted]_ using code should be written by subclassing the
+  ``TestCase`` class that comes with ``twisted.trial.unittest``.
+
+.. _devel_testing:
+
+Older material
+==============
+
+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
+[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.
+
+Tests of Twisted using code need to follow two additional guidelines:
+
+1. Twisted using tests should be written by subclassing the :class:`TestCase`
+   class that comes with :mod:`twisted.trial.unittest`. 
+
+2. All :class:`Deferred` instances that are created in the test must be
+   properly chained and the final one *must* be the return value of the test
+   method.
+
+When these two things are done, Nose will be able to run the tests and the
+twisted reactor will be handled correctly.
+
+Each subpackage in IPython should have its own :file:`tests` directory that
+contains all of the tests for that subpackage. This allows each subpackage to
+be self-contained.  A good convention to follow is to have a file named
+:file:`test_foo.py` for each module :file:`foo.py` in the package.  This makes
+it easy to organize the tests, though like most conventions, it's OK to break
+it if logic and common sense dictate otherwise.
+
+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 ship a set of decorators in the
+:mod:`IPython.testing` package to tag tests that may be platform-specific or
+otherwise may have restrictions; if the existing ones don't fit your needs, add
+a new decorator in that location so other tests can reuse it.
+
+To run the IPython test suite, use the :command:`iptest` command that is
+installed with IPython (if you are using IPython in-place, without installing
+it, you can find this script in the :file:`scripts` directory)::
+
+    $ iptest
+
+This command colects all IPython tests into separate groups, and then calls
+either Nose with the proper options and extensions, or Twisted's
+:command:`trial`.  This ensures that tests that need the Twisted reactor
+management facilities execute separate of Nose.  If any individual test group
+fails, :command:`iptest` will print what you need to type so you can rerun that
+particular test group alone for debugging.
+
+By default, :command:`iptest` runs the entire IPython test
+suite (skipping tests that may be platform-specific or which depend on tools
+you may not have).  But you can also use it to run only one specific test file,
+or a specific test function.  For example, this will run only the
+:file:`test_magic` file from the test suite::
+
+    $ iptest IPython.tests.test_magic
+    ----------------------------------------------------------------------
+    Ran 10 tests in 0.348s
+
+    OK (SKIP=3)
+    Deleting object: second_pass
+
+while the ``path:function`` syntax allows you to select a specific function in
+that file to run::
+
+    $ iptest IPython.tests.test_magic:test_obj_del
+    ----------------------------------------------------------------------
+    Ran 1 test in 0.204s
+
+    OK
+
+Since :command:`iptest` is based on nosetests, you can pass it any regular
+nosetests option.  For example, you can use ``--pdb`` or ``--pdb-failures`` to
+automatically activate the interactive Pdb debugger on errors or failures.  See
+the nosetests documentation for further details.
+
+
+A few tips for writing tests
+----------------------------
+
+You can write tests either as normal test files, using all the conventions that
+Nose recognizes, or as doctests.  Note that *all* IPython functions should have
+at least one example that serves as a doctest, whenever technically feasible.
+However, example doctests should only be in the main docstring if they are *a
+good example*, i.e. if they convey useful information about the function.  If
+you simply would like to write a test as a doctest, put it in a separate test
+file and write a no-op function whose only purpose is its docstring.
+
+Note, however, that in a file named :file:`test_X`, functions whose only test
+is their docstring (as a doctest) and which have no test functionality of their
+own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
+double-counted (the empty function call is counted as a test, which just
+inflates tests numbers artificially).  This restriction does not apply to
+functions in files with other names, due to how Nose discovers tests.
+
+You can use IPython examples in your docstrings.  Those can make full use of
+IPython functionality (magics, variable substitution, etc), but be careful to
+keep them generic enough that they run identically on all Operating Systems.
+
+The prompts in your doctests can be either of the plain Python ``>>>`` variety
+or ``In [1]:`` IPython style.  Since this is the IPython system, after all, we
+encourage you to use IPython prompts throughout, unless you are illustrating a
+specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
+
+If a test isn't safe to run inside the main nose process (e.g. because it loads
+a GUI toolkit), consider running it in a subprocess and capturing its output
+for evaluation and test decision later.  Here is an example of how to do it, by
+relying on the builtin ``_ip`` object that contains the public IPython api as
+defined in :mod:`IPython.ipapi`::
+
+   def test_obj_del():
+       """Test that object's __del__ methods are called on exit."""
+       test_dir = os.path.dirname(__file__)
+       del_file = os.path.join(test_dir,'obj_del.py')
+       out = _ip.IP.getoutput('ipython %s' % del_file)
+       nt.assert_equals(out,'object A deleted')
+
+
+
+If a doctest contains input whose output you don't want to verify identically
+via doctest (random output, an object id, etc), you can mark a docstring with
+``#random``.  All of these test will have their code executed but no output
+checking will be done::
+
+       >>> 1+3
+       junk goes here...  # random
+
+       >>> 1+2
+       again,  anything goes #random
+       if multiline, the random mark is only needed once.
+
+       >>> 1+2
+       You can also put the random marker at the end:
+       # random
+
+       >>> 1+2
+       # random
+       .. or at the beginning.
+
+In a case where you want an *entire* docstring to be executed but not verified
+(this only serves to check that the code runs without crashing, so it should be
+used very sparingly), you can put ``# all-random`` in the docstring.
+

docs/source/about/credits.txt

@@ -4,205 +4,206 b''
 Credits
 =======
 
-IPython is led by Fernando Pérez.
+IPython was started and continues to be led by Fernando Pérez.
 
-As of this writing, the following developers have joined the core team:
+Core developers
+===============
 
-* [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
-  Google Summer of Code project to develop python interactive
-  notebooks (XML documents) and graphical interface. This project
-  was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
-  Toni Alatalo <antont-AT-an.org>.
+As of this writing, core development team consists of the following
+developers:
 
-* [Brian Granger] <ellisonbg-AT-gmail.com>: extending IPython to allow
-  support for interactive parallel computing.
+* **Fernando Pérez** <Fernando.Perez-AT-berkeley.edu> Project creator and leader, 
+  IPython core, parallel computing infrastructure, testing, release manager.
 
-* [Benjamin (Min) Ragan-Kelley]: key work on IPython's parallel
-  computing infrastructure.
+* **Robert Kern** <rkern-AT-enthought.com> Co-mentored the 2005 Google Summer of
+  Code project, work on IPython's core.
 
-* [Ville Vainio] <vivainio-AT-gmail.com>: Ville has made many improvements
-  to the core of IPython and was the maintainer of the main IPython
-  trunk from version 0.7.1 to 0.8.4.
+* **Brian Granger** <ellisonbg-AT-gmail.com> Parallel computing 
+  infrastructure, IPython core.
 
-* [Gael Varoquaux] <gael.varoquaux-AT-normalesup.org>: work on the merged
-  architecture for the interpreter as of version 0.9, implementing a new WX GUI
-  based on this system.
+* **Benjamin (Min) Ragan-Kelley** <benjaminrk-AT-gmail.com> Parallel computing
+  infrastructure.
 
-* [Barry Wark] <barrywark-AT-gmail.com>: implementing a new Cocoa GUI, as well
-  as work on the new interpreter architecture and Twisted support.
+* **Ville Vainio** <vivainio-AT-gmail.com> IPython core, maintainer of IPython
+  trunk from version 0.7.2 to 0.8.4.
 
-* [Laurent Dufrechou] <laurent.dufrechou-AT-gmail.com>: development of the WX
-  GUI support.
+* **Gael Varoquaux** <gael.varoquaux-AT-normalesup.org> wxPython IPython GUI,
+  frontend architecture.
 
-* [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu>: maintainer of the
-  PyReadline project, necessary for IPython under windows.
+* **Barry Wark** <barrywark-AT-gmail.com> Cocoa GUI, frontend architecture.
 
+* **Laurent Dufrechou** <laurent.dufrechou-AT-gmail.com> wxPython IPython GUI.
+
+* **Jörgen Stenarson** <jorgen.stenarson-AT-bostream.nu> Maintainer of the
+  PyReadline project, which is needed for IPython under windows.
+
+Special thanks
+==============
 
 The IPython project is also very grateful to:
 
-Bill Bumgarner <bbum-AT-friday.com>: for providing the DPyGetOpt module
-which gives very powerful and convenient handling of command-line
-options (light years ahead of what Python 2.1.1's getopt module does).
+Bill Bumgarner <bbum-AT-friday.com>, for providing the DPyGetOpt module that
+IPython used for parsing command line options through version 0.10.
 
-Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for
-convenient and powerful string interpolation with a much nicer syntax
-than formatting through the '%' operator.
+Ka-Ping Yee <ping-AT-lfw.org>, for providing the Itpl module for convenient
+and powerful string interpolation with a much nicer syntax than formatting
+through the '%' operator.
 
-Arnd Baecker <baecker-AT-physik.tu-dresden.de>: for his many very useful
-suggestions and comments, and lots of help with testing and
-documentation checking. Many of IPython's newer features are a result of
-discussions with him (bugs are still my fault, not his).
+Arnd Baecker <baecker-AT-physik.tu-dresden.de>, for his many very useful
+suggestions and comments, and lots of help with testing and documentation
+checking. Many of IPython's newer features are a result of discussions with
+him.
 
-Obviously Guido van Rossum and the whole Python development team, that
-goes without saying.
+Obviously Guido van Rossum and the whole Python development team, for creating
+a great language for interactive computing.
 
-IPython's website is generously hosted at http://ipython.scipy.orgby
-Enthought (http://www.enthought.com). I am very grateful to them and all
-of the SciPy team for their contribution.
+Enthought (http://www.enthought.com), for hosting IPython's website and
+supporting the project in various ways over the years.
 
 Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>,
-an O'Reilly Python editor. His Oct/11/2001 article about IPP and
-LazyPython, was what got this project started. You can read it at:
+an O'Reilly Python editor. His October 11, 2001 article about IPP and
+LazyPython, was what got this project started. You can read it at
 http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html.
 
-And last but not least, all the kind IPython users who have emailed new code,
-bug reports, fixes, comments and ideas. A brief list follows, please let us
-know if we have ommitted your name by accident:
+Contributors
+============
+
+And last but not least, all the kind IPython contributors who have contributed
+new code, bug reports, fixes, comments and ideas. A brief list follows, please
+let us know if we have omitted your name by accident:
 
-* Dan Milstein <danmil-AT-comcast.net>.  A bold refactoring of the 
-  core prefilter stuff in the IPython interpreter.
+* Dan Milstein <danmil-AT-comcast.net> A bold refactor of the core prefilter
+  machinery in the IPython interpreter.
 
-* [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous
-  color problem. This bug alone caused many lost hours and
-  frustration, many thanks to him for the fix. I've always been a
-  fan of Ogg & friends, now I have one more reason to like these folks.
-  Jack is also contributing with Debian packaging and many other
-  things.
+* Jack Moffit <jack-AT-xiph.org> Bug fixes, including the infamous color
+  problem. This bug alone caused many lost hours and frustration, many thanks
+  to him for the fix. I've always been a fan of Ogg & friends, now I have one
+  more reason to like these folks. Jack is also contributing with Debian
+  packaging and many other things.
  
-* [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug
-  reports, bug fixes, ideas, lots more. The ipython.el mode for
-  (X)Emacs is Alex's code, providing full support for IPython under
-  (X)Emacs.
+* Alexander Schmolck <a.schmolck-AT-gmx.net> Emacs work, bug reports, bug
+  fixes, ideas, lots more. The ipython.el mode for (X)Emacs is Alex's code,
+  providing full support for IPython under (X)Emacs.
 
-* [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
-  information, Fink package management.
+* Andrea Riciputi <andrea.riciputi-AT-libero.it> Mac OSX information, Fink
+  package management.
 
-* [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
-  around the exception handling idiosyncracies of WxPython. Readline
-  and color support for Windows.
+* Gary Bishop <gb-AT-cs.unc.edu> Bug reports, and patches to work around the
+  exception handling idiosyncracies of WxPython. Readline and color support
+  for Windows.
 
-* [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
-  improved readline support, including fixes for Python 2.3.
+* Jeffrey Collins <Jeff.Collins-AT-vexcel.com>. Bug reports. Much improved
+  readline support, including fixes for Python 2.3.
 
-* [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
+* Dryice Liu <dryice-AT-liu.com.cn> FreeBSD port.
 
-* [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
+* Mike Heeter <korora-AT-SDF.LONESTAR.ORG>
 
-* [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
+* Christopher Hart <hart-AT-caltech.edu> PDB integration.
 
-* [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
+* Milan Zamazal <pdm-AT-zamazal.org> Emacs info.
 
-* [Philip Hisley] <compsys-AT-starpower.net>
+* Philip Hisley <compsys-AT-starpower.net>
 
-* [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
-  more.
+* Holger Krekel <pyth-AT-devel.trillke.net> Tab completion, lots more.
 
-* [Robin Siebler] <robinsiebler-AT-starband.net>
+* Robin Siebler <robinsiebler-AT-starband.net>
 
-* [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
+* Ralf Ahlbrink <ralf_ahlbrink-AT-web.de>
 
-* [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
+* Thorsten Kampe <thorsten-AT-thorstenkampe.de>
 
-* [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
+* Fredrik Kant <fredrik.kant-AT-front.com> Windows setup.
 
-* [Syver Enstad] <syver-en-AT-online.no> Windows setup.
+* Syver Enstad <syver-en-AT-online.no> Windows setup.
 
-* [Richard] <rxe-AT-renre-europe.com> Global embedding.
+* Richard <rxe-AT-renre-europe.com> Global embedding.
 
-* [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
+* Hayden Callow <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
   compatibility.
   
-* [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
+* Leonardo Santagada <retype-AT-terra.com.br> Fixes for Windows
   installation.
   
-* [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
+* Christopher Armstrong <radix-AT-twistedmatrix.com> Bugfixes.
 
-* [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
+* Francois Pinard <pinard-AT-iro.umontreal.ca> Code and
   documentation fixes.
   
-* [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
+* Cory Dodt <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
   ideas. Patches for Windows installer.
   
-* [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
+* Olivier Aubert <oaubert-AT-bat710.univ-lyon1.fr> New magics.
 
-* [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
+* King C. Shu <kingshu-AT-myrealbox.com> Autoindent patch.
 
-* [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
+* Chris Drexler <chris-AT-ac-drexler.de> Readline packages for
   Win32/CygWin.
   
-* [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
+* Gustavo Cordova Avila <gcordova-AT-sismex.com> EvalDict code for
   nice, lightweight string interpolation.
   
-* [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
+* Kasper Souren <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
 
-* [Gever Tulley] <gever-AT-helium.com> Code contributions.
+* Gever Tulley <gever-AT-helium.com> Code contributions.
 
-* [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
+* Ralf Schmitt <ralf-AT-brainbot.com> Bug reports & fixes.
 
-* [Oliver Sander] <osander-AT-gmx.de> Bug reports.
+* Oliver Sander <osander-AT-gmx.de> Bug reports.
 
-* [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
+* Rod Holland <rhh-AT-structurelabs.com> Bug reports and fixes to
   logging module.
 
-* [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
+* Daniel 'Dang' Griffith <pythondev-dang-AT-lazytwinacres.net>
   Fixes, enhancement suggestions for system shell use.
 
-* [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
+* Viktor Ransmayr <viktor.ransmayr-AT-t-online.de> Tests and
   reports on Windows installation issues. Contributed a true Windows
   binary installer.
 
-* [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
+* Mike Salib <msalib-AT-mit.edu> Help fixing a subtle bug related
   to traceback printing.
 
-* [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
+* W.J. van der Laan <gnufnork-AT-hetdigitalegat.nl> Bash-like
   prompt specials.
 
-* [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
+* Antoon Pardon <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
   the multithreaded IPython.
 
-* [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
+* John Hunter <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
   author, helped with all the development of support for matplotlib
   in IPyhton, including making necessary changes to matplotlib itself.
 
-* [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
+* Matthew Arnison <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
 
-* [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
+* Prabhu Ramachandran <prabhu_r-AT-users.sourceforge.net> Help
   with (X)Emacs support, threading patches, ideas...
 
-* [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
+* Norbert Tretkowski <tretkowski-AT-inittab.de> help with Debian
   packaging and distribution.
 
-* [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
+* George Sakkis <gsakkis-AT-eden.rutgers.edu> New matcher for
   tab-completing named arguments of user-defined functions.
 
-* [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
+* Jörgen Stenarson <jorgen.stenarson-AT-bostream.nu> Wildcard
   support implementation for searching namespaces.
 
-* [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
+* Vivian De Smedt <vivian-AT-vdesmedt.com> Debugger enhancements,
   so that when pdb is activated from within IPython, coloring, tab
   completion and other features continue to work seamlessly.
 
-* [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
+* Scott Tsai <scottt958-AT-yahoo.com.tw> Support for automatic
   editor invocation on syntax errors (see
   http://www.scipy.net/roundup/ipython/issue36).
 
-* [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
+* Alexander Belchenko <bialix-AT-ukr.net> Improvements for win32
   paging system.
 
-* [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
+* Will Maier <willmaier-AT-ml1.net> Official OpenBSD port.
 
-* [Ondrej Certik] <ondrej-AT-certik.cz>: set up the IPython docs to use the new
+* Ondrej Certik <ondrej-AT-certik.cz> Set up the IPython docs to use the new
   Sphinx system used by Python, Matplotlib and many more projects.
 
-* [Stefan van der Walt] <stefan-AT-sun.ac.za>: support for the new config system.
+* Stefan van der Walt <stefan-AT-sun.ac.za> Design and prototype of the
+  Traits based config system.
 

docs/source/about/history.txt

@@ -7,21 +7,22 b' History'
 Origins
 =======
 
-IPython was starting in 2001 by Fernando Perez.  IPython as we know it
-today grew out of the following three projects:
-
-* ipython by Fernando Pérez. I was working on adding
-  Mathematica-type prompts and a flexible configuration system
-  (something better than $PYTHONSTARTUP) to the standard Python
-  interactive interpreter.
+IPython was starting in 2001 by Fernando Perez while he was a graduate student
+at the University of Colorado, Boulder. IPython as we know it today grew out
+of the following three projects:
+
+* ipython by Fernando Pérez. Fernando began using Python and ipython began as
+  an outgrowth of his desire for things like Mathematica-style prompts, access
+  to previous output (again like Mathematica's % syntax) and a flexible
+  configuration system (something better than :envvar:`PYTHONSTARTUP`).
 * IPP by Janko Hauser. Very well organized, great usability. Had
-  an old help system. IPP was used as the 'container' code into
-  which I added the functionality from ipython and LazyPython.
+  an old help system. IPP was used as the "container" code into
+  which Fernando added the functionality from ipython and LazyPython.
 * LazyPython by Nathan Gray. Simple but very powerful. The quick
   syntax (auto parens, auto quotes) and verbose/colored tracebacks
   were all taken from here.
 
-Here is how Fernando describes it:
+Here is how Fernando describes the early history of IPython:
 
     When I found out about IPP and LazyPython I tried to join all three
     into a unified system. I thought this could provide a very nice
@@ -31,8 +32,3 b' Here is how Fernando describes it:'
     think it worked reasonably well, though it was a lot more work than I
     had initially planned.
 
-Today and how we got here
-=========================
-
-This needs to be filled in.
-

docs/source/about/license_and_copyright.txt

@@ -7,7 +7,8 b' License and Copyright'
 License
 =======
 
-IPython is licensed under the terms of the new or revised BSD license, as follows::
+IPython is licensed under the terms of the new or revised BSD license, as
+follows::
 
     Copyright (c) 2008, IPython Development Team
 
@@ -44,7 +45,7 b' About the IPython Development Team'
 ==================================
 
 Fernando Perez began IPython in 2001 based on code from Janko Hauser
-<[e-mail]> and Nathaniel Gray <[e-mail]>. Fernando is still
+<jhauser-AT-zscout.de> and Nathaniel Gray <n8gray-AT-caltech.edu>. Fernando is still
 the project lead.
 
 The IPython Development Team is the set of all contributors to the IPython
@@ -61,7 +62,6 b' currently active contributors:'
 	* Ville M. Vainio
 	* Gael Varoququx
 	* Stefan van der Walt
-	* Tech-X Corporation
 	* Barry Wark
 
 If your name is missing, please add it.  
@@ -71,13 +71,16 b' Our Copyright Policy'
 
 IPython uses a shared copyright model. Each contributor maintains copyright
 over their contributions to IPython. But, it is important to note that these
-contributions are typically only changes to the repositories. Thus, the
-IPython source code, in its entirety is not the copyright of any single person
-or institution. Instead, it is the collective copyright of the entire IPython
-Development Team. If individual contributors want to maintain a record of what
-changes/contributions they have specific copyright on, they should indicate
-their copyright in the commit message of the change, when they commit the
-change to one of the IPython repositories.
+contributions are typically only changes (diffs/commits) to the repositories.
+Thus, the IPython source code, in its entirety is not the copyright of any
+single person or institution. Instead, it is the collective copyright of the
+entire IPython Development Team. If individual contributors want to maintain a
+record of what changes/contributions they have specific copyright on, they
+should indicate their copyright in the commit message of the change, when they
+commit the change to one of the IPython repositories.
+
+Any new code contributed to IPython must be licensed under the BSD license or
+a similar (MIT) open source license.
 
 Miscellaneous
 =============

docs/source/development/coding_guide.txt

@@ -79,64 +79,78 b' 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.
 
+Older material
+==============
 
-.. _devel-testing:
+General
+-------
 
-Testing system
-==============
+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 an interface.
+
+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.
+
+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.
 
-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

@@ -102,3 +102,40 b' machinery to process reStructuredText):'
 - `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
 - `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
 
+Older material
+==============
+
+Documentation
+=============
+
+Standalone documentation
+------------------------
+
+All standalone documentation should be written in plain text (``.txt``) files
+using reStructuredText [reStructuredText]_ for markup and formatting. All such
+documentation should be placed in directory :file:`docs/source` of the IPython
+source tree. The documentation in this location will serve as the main source
+for IPython documentation and all existing documentation should be converted
+to this format.
+
+To build the final documentation, we use Sphinx [Sphinx]_.  Once you have
+Sphinx installed, you can build the html docs yourself by doing::
+
+    $ cd ipython-mybranch/docs
+    $ make html
+
+Docstring format
+----------------
+
+Good docstrings are very important. All new code should have docstrings that
+are formatted using reStructuredText for markup and formatting, since it is
+understood by a wide variety of tools. Details about using reStructuredText
+for docstrings can be found `here
+<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
+
+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,16 +1,25 b''
-===========================
- IPython Developer's Guide
-===========================
+.. _developer_guide:
+
+=========================
+IPython developer's guide
+=========================
 
 .. toctree::
    :maxdepth: 2
 
-   overview.txt
+   contributing.txt
    coding_guide.txt
    doc_guide.txt
+   testing.txt
+   release.txt
    roadmap.txt
 
    notification_blueprint.txt
-   config_blueprint.txt
    reorg.txt
 
+
+.. [Bazaar] Bazaar. http://bazaar-vcs.org/
+.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
+.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
+.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
+.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
  No newline at end of file

docs/source/development/notification_blueprint.txt

@@ -39,20 +39,29 b' The notification center must:'
 What's not included
 ===================
 
-As written, the :mod:`IPython.kernel.core.notificaiton` module does not:
+As written, the :mod:`IPython.kernel.core.notification` module does not:
 
 * Provide out-of-process or network notifications (these should be handled by
   a separate, Twisted aware module in :mod:`IPython.kernel`).
 
-* Provide zope.interface-style interfaces for the notification system (these
+* Provide zope.interface style interfaces for the notification system (these
   should also be provided by the :mod:`IPython.kernel` module).
     
 Use Cases
 =========
 
-The following use cases describe the main intended uses of the notificaiton module and illustrate the main success scenario for each use case:
+The following use cases describe the main intended uses of the notification
+module and illustrate the main success scenario for each use case:
 
-    1. Dwight Schroot is writing a frontend for the IPython project. His frontend is stuck in the stone age and must communicate synchronously with an IPython.kernel.core.Interpreter instance. Because code is executed in blocks by the Interpreter, Dwight's UI freezes every time he executes a long block of code. To keep track of the progress of his long running block, Dwight adds the following code to his frontend's set-up code::
+Scenario 1
+----------
+
+Dwight Schroot is writing a frontend for the IPython project. His frontend is
+stuck in the stone age and must communicate synchronously with an
+:mod:`IPython.kernel.core.Interpreter` instance. Because code is executed in blocks
+by the Interpreter, Dwight's UI freezes every time he executes a long block of
+code. To keep track of the progress of his long running block, Dwight adds the
+following code to his frontend's set-up code::
 
         from IPython.kernel.core.notification import NotificationCenter
         center = NotificationCenter.sharedNotificationCenter
@@ -78,7 +87,10 b" Like magic, Dwight's frontend is able to provide output, even during"
 long-running calculations. Now if Jim could just convince Dwight to use
 Twisted...
 
-2. Boss Hog is writing a frontend for the IPython project. Because Boss Hog is
+Scenario 2
+----------
+
+Boss Hog is writing a frontend for the IPython project. Because Boss Hog is
 stuck in the stone age, his frontend will be written in a new Fortran-like
 dialect of python and will run only from the command line. Because he doesn't
 need any fancy notification system and is used to worrying about every cycle
@@ -93,16 +105,19 b' registered observers. Of course, the same notificaiton-enabled Interpreter can'
 then be used in frontends that require notifications, thus saving the IPython
 project from a nasty civil war.
     
-3. Barry is wrting a frontend for the IPython project. Because Barry's front
-end is the *new hotness*, it uses an asynchronous event model to communicate
-with a Twisted :mod:`~IPython.kernel.engineservice` that communicates with the
-IPython :class:`~IPython.kernel.core.interpreter.Interpreter`. Using the
+Scenario 3
+----------
+
+Barry is wrting a frontend for the IPython project. Because Barry's front end
+is the *new hotness*, it uses an asynchronous event model to communicate with
+a Twisted :mod:`IPython.kernel.engineservice` that communicates with the
+IPython :class:`IPython.kernel.core.interpreter.Interpreter`. Using the
 :mod:`IPython.kernel.notification` module, an asynchronous wrapper on the
 :mod:`IPython.kernel.core.notification` module, Barry's frontend can register
 for notifications from the interpreter that are delivered asynchronously. Even
 if Barry's frontend is running on a separate process or even host from the
 Interpreter, the notifications are delivered, as if by dark and twisted magic.
-Just like Dwight's frontend, Barry's frontend can now recieve notifications of
+Just like Dwight's frontend, Barry's frontend can now receive notifications of
 e.g. writing to stdout/stderr, opening/closing an external file, an exception
 in the executing code, etc.
 

docs/source/development/overview.txt

@@ -1,518 +1,8 b''
-.. _development:
 
-==============================
-IPython development guidelines
-==============================
 
 
-Overview
-========
 
-This document describes IPython from the perspective of developers. Most
-importantly, it gives information for people who want to contribute to the
-development of IPython. So if you want to help out, read on!
 
-How to contribute to IPython
-============================
 
-IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
-This makes it easy for people to contribute to the development of IPython.
-There are several ways in which you can join in.
 
-If you have a small change that you want to send to the team, you can edit your
-bazaar checkout of IPython (see below) in-place, and ask bazaar for the
-differences::
-
-    $ cd /path/to/your/copy/of/ipython
-    $ bzr diff > my_fixes.diff
-
-This produces a patch file with your fixes, which we can apply to the source
-tree.  This file should then be attached to a ticket in our `bug tracker
-<https://bugs.launchpad.net/ipython>`_, indicating what it does.
-
-This model of creating small, self-contained patches works very well and there
-are open source projects that do their entire development this way.  However,
-in IPython we have found that for tracking larger changes, making use of
-bazaar's full capabilities in conjunction with Launchpad's code hosting
-services makes for a much better experience.
-
-Making your own branch of IPython allows you to refine your changes over time,
-track the development of the main team, and propose your own full version of
-the code for others to use and review, with a minimum amount of fuss.  The next
-parts of this document will explain how to do this.
-
-Install Bazaar and create a Launchpad account
----------------------------------------------
-
-First make sure you have installed Bazaar (see their `website
-<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
-you, try the following::
-
-    $ bzr whoami
-    Joe Coder <[e-mail]>
-
-This should display your name and email. Next, you will want to create an
-account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
-ssh keys. For more information of setting up your ssh keys, see `this link
-<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
-
-Get the main IPython branch from Launchpad
-------------------------------------------
-
-Now, you can get a copy of the main IPython development branch (we call this
-the "trunk")::
-
-    $ bzr branch lp:ipython
-
-Create a working branch
------------------------
-
-When working on IPython, you won't actually make edits directly to the
-:file:`lp:ipython` branch. Instead, you will create a separate branch for your
-changes. For now, let's assume you want to do your work in a branch named
-"ipython-mybranch". Create this branch by doing::
-
-    $ bzr branch ipython ipython-mybranch
-
-When you actually create a branch, you will want to give it a name that
-reflects the nature of the work that you will be doing in it, like
-"install-docs-update".
-
-Make edits in your working branch
----------------------------------
-
-Now you are ready to actually make edits in your :file:`ipython-mybranch`
-branch. Before doing this, it is helpful to install this branch so you can
-test your changes as you work. This is easiest if you have setuptools
-installed. Then, just do::
-
-    $ cd ipython-mybranch
-    $ python setupegg.py develop
-
-Now, make some changes. After a while, you will want to commit your changes.
-This let's Bazaar know that you like the changes you have made and gives you
-an opportunity to keep a nice record of what you have done. This looks like
-this::
-
-    $ ...do work in ipython-mybranch...
-    $ bzr commit -m "the commit message goes here"
-
-Please note that since we now don't use an old-style linear ChangeLog (that
-tends to cause problems with distributed version control systems), you should
-ensure that your log messages are reasonably detailed.  Use a docstring-like
-approach in the commit messages (including the second line being left
-*blank*)::
-
-  Single line summary of  changes being committed.
-
-  * more details when warranted ...
-  * including crediting outside contributors if they sent the
-    code/bug/idea!
-
-As you work, you will repeat this edit/commit cycle many times. If you work on
-your branch for a long time, you will also want to get the latest changes from
-the :file:`lp:ipython` branch. This can be done with the following sequence of
-commands::
-
-    $ ls
-    ipython
-    ipython-mybranch
-    
-    $ cd ipython
-    $ bzr pull
-    $ cd ../ipython-mybranch
-    $ bzr merge ../ipython
-    $ bzr commit -m "Merging changes from trunk"
-
-Along the way, you should also run the IPython test suite.  You can do this
-using the :command:`iptest` command (which is basically a customized version of
-:command:`nosetests`)::
-
-    $ cd
-    $ iptest
-
-The :command:`iptest` command will also pick up and run any tests you have
-written. See :ref:`testing documentation <devel_testing>` for further details
-on the testing system.
-
-
-Post your branch and request a code review
-------------------------------------------
-
-Once you are done with your edits, you should post your branch on Launchpad so
-that other IPython developers can review the changes and help you merge your
-changes into the main development branch. To post your branch on Launchpad,
-do::
-
-    $ cd ipython-mybranch
-    $ bzr push lp:~yourusername/ipython/ipython-mybranch
-
-Then, go to the `IPython Launchpad site <www.launchpad.net/ipython>`_, and you
-should see your branch under the "Code" tab. If you click on your branch, you
-can provide a short description of the branch as well as mark its status. Most
-importantly, you should click the link that reads "Propose for merging into
-another branch". What does this do?
-
-This let's the other IPython developers know that your branch is ready to be
-reviewed and merged into the main development branch. During this review
-process, other developers will give you feedback and help you get your code
-ready to be merged. What types of things will we be looking for:
-
-* All code is documented.
-* All code has tests.
-* The entire IPython test suite passes.
-
-Once your changes have been reviewed and approved, someone will merge them
-into the main development branch.
-
-
-Some notes for core developers when merging third-party contributions
-=====================================================================
-
-Core developers, who ultimately merge any approved branch (from themselves,
-another developer, or any third-party contribution) will typically use
-:command:`bzr merge` to merge the branch into the trunk and push it to the
-main Launcphad site. This is a short list of things to keep in mind when doing
-this process, so that the project history is easy to understand in the long
-run, and that generating release notes is as painless and accurate as
-possible.
-
-- When you merge any non-trivial functionality (from one small bug fix to a
-  big feature branch), please remember to always edit the :file:`changes.txt`
-  file accordingly. This file has one main section for each release, and if
-  you edit it as you go, noting what new features, bug fixes or API changes
-  you have made, the release notes will be almost finished when they are
-  needed later. This is much easier if done when you merge the work, rather
-  than weeks or months later by re-reading a massive Bazaar log.
-
-- When big merges are done, the practice of putting a summary commit message
-  in the merge is *extremely* useful. It makes this kind of job much nicer,
-  because that summary log message can be almost copy/pasted without changes,
-  if it was well written, rather than dissecting the next-level messages from
-  the individual commits.
-
-- It's important that we remember to always credit who gave us something if
-  it's not the committer. In general, we have been fairly good on this front,
-  this is just a reminder to keep things up. As a note, if you are ever
-  committing something that is completely (or almost so) a third-party
-  contribution, do the commit as::
-
-    $ bzr commit --author="Someone Else"
-
-  This way it will show that name separately in the log, which makes it even
-  easier to spot. Obviously we often rework third party contributions
-  extensively, but this is still good to keep in mind for cases when we don't
-  touch the code too much.
-
-
-Documentation
-=============
-
-Standalone documentation
-------------------------
-
-All standalone documentation should be written in plain text (``.txt``) files
-using reStructuredText [reStructuredText]_ for markup and formatting. All such
-documentation should be placed in directory :file:`docs/source` of the IPython
-source tree. The documentation in this location will serve as the main source
-for IPython documentation and all existing documentation should be converted
-to this format.
-
-To build the final documentation, we use Sphinx [Sphinx]_.  Once you have
-Sphinx installed, you can build the html docs yourself by doing::
-
-    $ cd ipython-mybranch/docs
-    $ make html
-
-Docstring format
-----------------
-
-Good docstrings are very important. All new code should have docstrings that
-are formatted using reStructuredText for markup and formatting, since it is
-understood by a wide variety of tools. Details about using reStructuredText
-for docstrings can be found `here
-<http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
-
-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>`_
-
-
-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 an interface.
-
-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.
-
-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
-[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.
-
-Tests of Twisted using code need to follow two additional guidelines:
-
-1. Twisted using tests should be written by subclassing the :class:`TestCase`
-   class that comes with :mod:`twisted.trial.unittest`. 
-
-2. All :class:`Deferred` instances that are created in the test must be
-   properly chained and the final one *must* be the return value of the test
-   method.
-
-When these two things are done, Nose will be able to run the tests and the
-twisted reactor will be handled correctly.
-
-Each subpackage in IPython should have its own :file:`tests` directory that
-contains all of the tests for that subpackage. This allows each subpackage to
-be self-contained.  A good convention to follow is to have a file named
-:file:`test_foo.py` for each module :file:`foo.py` in the package.  This makes
-it easy to organize the tests, though like most conventions, it's OK to break
-it if logic and common sense dictate otherwise.
-
-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 ship a set of decorators in the
-:mod:`IPython.testing` package to tag tests that may be platform-specific or
-otherwise may have restrictions; if the existing ones don't fit your needs, add
-a new decorator in that location so other tests can reuse it.
-
-To run the IPython test suite, use the :command:`iptest` command that is
-installed with IPython (if you are using IPython in-place, without installing
-it, you can find this script in the :file:`scripts` directory)::
-
-    $ iptest
-
-This command colects all IPython tests into separate groups, and then calls
-either Nose with the proper options and extensions, or Twisted's
-:command:`trial`.  This ensures that tests that need the Twisted reactor
-management facilities execute separate of Nose.  If any individual test group
-fails, :command:`iptest` will print what you need to type so you can rerun that
-particular test group alone for debugging.
-
-By default, :command:`iptest` runs the entire IPython test
-suite (skipping tests that may be platform-specific or which depend on tools
-you may not have).  But you can also use it to run only one specific test file,
-or a specific test function.  For example, this will run only the
-:file:`test_magic` file from the test suite::
-
-    $ iptest IPython.tests.test_magic
-    ----------------------------------------------------------------------
-    Ran 10 tests in 0.348s
-
-    OK (SKIP=3)
-    Deleting object: second_pass
-
-while the ``path:function`` syntax allows you to select a specific function in
-that file to run::
-
-    $ iptest IPython.tests.test_magic:test_obj_del
-    ----------------------------------------------------------------------
-    Ran 1 test in 0.204s
-
-    OK
-
-Since :command:`iptest` is based on nosetests, you can pass it any regular
-nosetests option.  For example, you can use ``--pdb`` or ``--pdb-failures`` to
-automatically activate the interactive Pdb debugger on errors or failures.  See
-the nosetests documentation for further details.
-
-
-A few tips for writing tests
-----------------------------
-
-You can write tests either as normal test files, using all the conventions that
-Nose recognizes, or as doctests.  Note that *all* IPython functions should have
-at least one example that serves as a doctest, whenever technically feasible.
-However, example doctests should only be in the main docstring if they are *a
-good example*, i.e. if they convey useful information about the function.  If
-you simply would like to write a test as a doctest, put it in a separate test
-file and write a no-op function whose only purpose is its docstring.
-
-Note, however, that in a file named :file:`test_X`, functions whose only test
-is their docstring (as a doctest) and which have no test functionality of their
-own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
-double-counted (the empty function call is counted as a test, which just
-inflates tests numbers artificially).  This restriction does not apply to
-functions in files with other names, due to how Nose discovers tests.
-
-You can use IPython examples in your docstrings.  Those can make full use of
-IPython functionality (magics, variable substitution, etc), but be careful to
-keep them generic enough that they run identically on all Operating Systems.
-
-The prompts in your doctests can be either of the plain Python ``>>>`` variety
-or ``In [1]:`` IPython style.  Since this is the IPython system, after all, we
-encourage you to use IPython prompts throughout, unless you are illustrating a
-specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
-
-If a test isn't safe to run inside the main nose process (e.g. because it loads
-a GUI toolkit), consider running it in a subprocess and capturing its output
-for evaluation and test decision later.  Here is an example of how to do it, by
-relying on the builtin ``_ip`` object that contains the public IPython api as
-defined in :mod:`IPython.ipapi`::
-
-   def test_obj_del():
-       """Test that object's __del__ methods are called on exit."""
-       test_dir = os.path.dirname(__file__)
-       del_file = os.path.join(test_dir,'obj_del.py')
-       out = _ip.IP.getoutput('ipython %s' % del_file)
-       nt.assert_equals(out,'object A deleted')
-
-
-
-If a doctest contains input whose output you don't want to verify identically
-via doctest (random output, an object id, etc), you can mark a docstring with
-``#random``.  All of these test will have their code executed but no output
-checking will be done::
-
-       >>> 1+3
-       junk goes here...  # random
-
-       >>> 1+2
-       again,  anything goes #random
-       if multiline, the random mark is only needed once.
-
-       >>> 1+2
-       You can also put the random marker at the end:
-       # random
-
-       >>> 1+2
-       # random
-       .. or at the beginning.
-
-In a case where you want an *entire* docstring to be executed but not verified
-(this only serves to check that the code runs without crashing, so it should be
-used very sparingly), you can put ``# all-random`` in the docstring.
-       
-.. _devel_config:
-
-Release checklist
-=================
-
-Most of the release process is automated by the :file:`release` script in the
-:file:`tools` directory.  This is just a handy reminder for the release manager.
-
-#. First, run :file:`build_release`, which does all the file checking and
-   building that the real release script will do.  This will let you do test
-   installations, check that the build procedure runs OK, etc.  You may want to
-   disable a few things like multi-version RPM building while testing, because
-   otherwise the build takes really long.
-
-#. Run the release script, which makes the tar.gz, eggs and Win32 .exe
-   installer.  It posts them to the site and registers the release with PyPI.
-
-#. Updating the website with announcements and links to the updated
-   changes.txt in html form. Remember to put a short note both on the news
-   page of the site and on Launcphad.
-
-#. Drafting a short release announcement with i) highlights and ii) a link to
-   the html changes.txt.
-
-#. Make sure that the released version of the docs is live on the site.
-
-#. Celebrate!
-
-Porting to 3.0
-==============
-
-There are no definite plans for porting of IPython to python 3. The major 
-issue is the dependency on twisted framework for the networking/threading 
-stuff. It is possible that it the traditional IPython interactive console 
-could be ported more easily since it has no such dependency. Here are a few
-things that will need to be considered when doing such a port especially
-if we want to have a codebase that works directly on both 2.x and 3.x.
-
-	1. The syntax for exceptions changed (PEP 3110). The old 
-	   `except exc, var` changed to `except exc as var`. At last
-	   count there was 78 occurences of this usage in the codebase.  This
-	   is  a particularly problematic issue, because it's not easy to
-	   implement it in a 2.5-compatible way.
-
-Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
-will likely at some point put out a release that requires strictly 2.6 and
-abandons 2.5 compatibility.  This will then allow us to port the code to using
-:func:`print` as a function, `except exc as var` syntax, etc.  But as of
-version 0.11 at least, we will retain Python 2.5 compatibility.
-
-
-.. [Bazaar] Bazaar. http://bazaar-vcs.org/
-.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
-.. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
-.. [Sphinx] Sphinx. http://sphinx.pocoo.org/
-.. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/
 

docs/source/development/roadmap.txt

@@ -92,3 +92,23 b' Currently, we have a number of performance issues in :mod:`IPython.kernel`:'
   separate the controller itself into multiple processes, one for the core
   controller and one each for the controller interfaces.
 
+Porting to 3.0
+==============
+
+There are no definite plans for porting of IPython to Python 3. The major 
+issue is the dependency on Twisted framework for the networking/threading 
+stuff. It is possible that it the traditional IPython interactive console 
+could be ported more easily since it has no such dependency. Here are a few
+things that will need to be considered when doing such a port especially
+if we want to have a codebase that works directly on both 2.x and 3.x.
+
+1. The syntax for exceptions changed (PEP 3110). The old `except exc, var`
+changed to `except exc as var`. At last count there was 78 occurrences of this
+usage in the code base. This is a particularly problematic issue, because it's
+not easy to implement it in a 2.5-compatible way.
+
+Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
+will likely at some point put out a release that requires strictly 2.6 and
+abandons 2.5 compatibility.  This will then allow us to port the code to using
+:func:`print` as a function, `except exc as var` syntax, etc.  But as of
+version 0.11 at least, we will retain Python 2.5 compatibility.

docs/source/faq.txt

@@ -91,6 +91,3 b' handling the data movement. Here are some ideas:'
 
 5. See if you can pass data directly between engines using MPI.
 
-Isn't Python slow to be used for high-performance parallel computing?
----------------------------------------------------------------------
-

docs/source/index.txt

@@ -7,8 +7,7 b' IPython Documentation'
    :Release: |release|
    :Date: |today|
 
-Welcome to the official IPython documentation.  This document describes the
-various parts of IPython that are relevant to both users and developers.
+Welcome to the official IPython documentation.
 
 Contents
 ========

docs/source/install/install.txt

@@ -34,16 +34,20 b' Quickstart'
 
 If you have :mod:`setuptools` installed and you are on OS X or Linux (not
 Windows), the following will download and install IPython *and* the main
-optional dependencies::
+optional dependencies:
 
-    $ easy_install ipython[kernel,security,test]
+.. code-block:: bash
+
+    easy_install ipython[kernel,security,test]
 
 This will get Twisted, zope.interface and Foolscap, which are needed for
 IPython's parallel computing features as well as the nose package, which will
 enable you to run IPython's test suite.  To run IPython's test suite, use the
-:command:`iptest` command::
+:command:`iptest` command:
+
+.. code-block:: bash
 
-    $ iptest
+    iptest
 
 Read on for more specific details and instructions for Windows.
 
@@ -62,9 +66,11 b' Installation using easy_install'
 -------------------------------
 
 If you have :mod:`setuptools` installed, the easiest way of getting IPython is
-to simple use :command:`easy_install`::
+to simple use :command:`easy_install`:
 
-	$ easy_install ipython
+.. code-block:: bash
+
+    easy_install ipython
 
 That's it.
 
@@ -73,11 +79,13 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::
+<http://ipython.scipy.org/dist/>`_.  Then do the following:
+
+.. code-block:: bash
 
-	$ tar -xzf ipython.tar.gz
-	$ cd ipython
-	$ python setup.py install
+    tar -xzf ipython.tar.gz
+    cd ipython
+    python setup.py install
 
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`.
@@ -98,7 +106,7 b' use any of the following alternatives:'
 3. Install from source, but using :mod:`setuptools` (``python setupegg.py
    install``).
 
-IPython by default runs in a termninal window, but the normal terminal
+IPython by default runs in a terminal window, but the normal terminal
 application supplied by Microsoft Windows is very primitive.  You may want to
 download the excellent and free Console_ application instead, which is a far
 superior tool.  You can even configure Console to give you by default an
@@ -113,26 +121,32 b' Installing the development version'
 
 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::
+need to have Bazaar installed on your system.  Then just do:
 
-	$ bzr branch lp:ipython
-	$ cd ipython
-	$ python setup.py install
+.. code-block:: bash
+
+    bzr branch lp:ipython
+    cd ipython
+    python setup.py install
 
 Again, this last step on Windows won't create ``.bat`` files or Start Menu
 shortcuts, so you will have to use one of the other approaches listed above.
 
 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::
+step by:
+
+.. code-block:: bash
 
-	$ python setupegg.py develop
+    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::
+just do:
+
+.. code-block:: bash
 
-	$ bzr pull
+    bzr pull
 
 Basic optional dependencies
 ===========================
@@ -165,9 +179,11 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)::
+working :mod:`readline` module, just do (with :mod:`setuptools` installed):
 
-	$ easy_install readline
+.. code-block:: bash
+
+    easy_install readline
 
 .. note:
 
@@ -190,28 +206,35 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`::
+simplest way of getting nose, is to use :command:`easy_install`:
+
+.. code-block:: bash
 
-	$ easy_install nose
+    easy_install nose
 
-Another way of getting this is to do::
+Another way of getting this is to do:
 
-    $ easy_install ipython[test]
+.. code-block:: bash
+
+    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::
+installed, you can run IPython's test suite using the iptest command:
 
-	$ iptest
+.. code-block:: bash
 
+    iptest
 
 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::
+:command:`irunner` script.  On Unix platforms (including OS X), just do:
+
+.. code-block:: bash
 
-	$ easy_install pexpect
+    easy_install pexpect
 
 Windows users are out of luck as pexpect does not run there.
 
@@ -227,36 +250,45 b' features require a number of additional packages:'
 * Foolscap (a nice, secure network protocol)
 * pyOpenSSL (security for network connections)
 
-On a Unix style platform (including OS X), if you want to use :mod:`setuptools`, you can just do::
+On a Unix style platform (including OS X), if you want to use
+:mod:`setuptools`, you can just do:
 
-    $ easy_install ipython[kernel]    # the first three
-    $ easy_install ipython[security]  # pyOpenSSL
+.. code-block:: bash
+
+    easy_install ipython[kernel]    # the first three
+    easy_install ipython[security]  # pyOpenSSL
 
 zope.interface and Twisted
 --------------------------
 
 Twisted [Twisted]_ and zope.interface [ZopeInterface]_ are used for networking
 related things. On Unix style platforms (including OS X), the simplest way of
-getting the these is to use :command:`easy_install`::
+getting the these is to use :command:`easy_install`:
+
+.. code-block:: bash
 
-	$ easy_install zope.interface
-	$ easy_install Twisted
+    easy_install zope.interface
+    easy_install Twisted
 
-Of course, you can also download the source tarballs from the `Twisted website
-<twistedmatrix.org>`_ and the `zope.interface page at PyPI
+Of course, you can also download the source tarballs from the Twisted website
+[Twisted]_ and the `zope.interface page at PyPI
 <http://pypi.python.org/pypi/zope.interface>`_ and do the usual ``python
 setup.py install`` if you prefer.
 
-Windows is a bit different.  For zope.interface and Twisted, simply get the latest binary ``.exe`` installer from the Twisted website.  This installer includes both zope.interface and Twisted and should just work.
+Windows is a bit different. For zope.interface and Twisted, simply get the
+latest binary ``.exe`` installer from the Twisted website. This installer
+includes both zope.interface and Twisted and should just work.
 
 Foolscap
 --------
 
 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::
+On all platforms a simple:
+
+.. code-block:: bash
 
-    $ easy_install foolscap
+    easy_install foolscap
 
 should work.  You can also download the source tarballs from the `Foolscap
 website <http://foolscap.lothar.com/trac>`_ and do ``python setup.py install``
@@ -265,14 +297,16 b' if you prefer.'
 pyOpenSSL
 ---------
 
-IPython requires an older version of pyOpenSSL [pyOpenSSL]_ (0.6 rather than
-the current 0.7).  There are a couple of options for getting this:
+IPython does not work with version 0.7 of pyOpenSSL [pyOpenSSL]_. It is known
+to work with version 0.6 and will likely work with the more recent 0.8 and 0.9
+versions. There are a couple of options for getting this:
 
 1.  Most Linux distributions have packages for pyOpenSSL.
 2.  The built-in Python 2.5 on OS X 10.5 already has it installed.
 3.  There are source tarballs on the pyOpenSSL website.  On Unix-like
     platforms, these can be built using ``python seutp.py install``.
-4.  There is also a binary ``.exe`` Windows installer on the `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
+4. There is also a binary ``.exe`` Windows installer on the 
+   `pyOpenSSL website <http://pyopenssl.sourceforge.net/>`_.
 
 Dependencies for IPython.frontend (the IPython GUI)
 ===================================================
@@ -280,11 +314,11 b' Dependencies for IPython.frontend (the IPython GUI)'
 wxPython
 --------
 
-Starting with IPython 0.9, IPython has a new IPython.frontend package that has
-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
+Starting with IPython 0.9, IPython has a new :mod:`IPython.frontend` package
+that has 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/>`_.
 
 .. [Twisted] Twisted matrix.  http://twistedmatrix.org

docs/source/interactive/index.txt

@@ -8,5 +8,5 b' Using IPython for interactive work'
    tutorial.txt
    reference.txt
    shell.txt
-   extension_api.txt
+
 

docs/source/interactive/reference.txt

@@ -2,6 +2,14 b''
 IPython reference
 =================
 
+.. warning::
+
+    As of the 0.11 version of IPython, some of the features and APIs
+    described in this section have been deprecated or are broken.  Our plan
+    is to continue to support these features, but they need to be updated
+    to take advantage of recent API changes.  Furthermore, this section
+    of the documentation need to be updated to reflect all of these changes.
+
 .. _command_line_options:
 
 Command-line usage

docs/source/interactive/shell.txt

@@ -4,6 +4,14 b''
 IPython as a system shell
 =========================
 
+.. warning::
+
+    As of the 0.11 version of IPython, some of the features and APIs
+    described in this section have been deprecated or are broken.  Our plan
+    is to continue to support these features, but they need to be updated
+    to take advantage of recent API changes.  Furthermore, this section
+    of the documentation need to be updated to reflect all of these changes.
+
 Overview
 ========
 

docs/source/interactive/tutorial.txt

@@ -4,6 +4,14 b''
 Quick IPython tutorial
 ======================
 
+.. warning::
+
+    As of the 0.11 version of IPython, some of the features and APIs
+    described in this section have been deprecated or are broken.  Our plan
+    is to continue to support these features, but they need to be updated
+    to take advantage of recent API changes.  Furthermore, this section
+    of the documentation need to be updated to reflect all of these changes.
+
 IPython can be used as an improved replacement for the Python prompt,
 and for that you don't really need to read any more of this manual. But
 in this section we'll try to summarize a few tips on how to make the

docs/source/overview.txt

@@ -219,9 +219,9 b' Portability and Python requirements'
 -----------------------------------
 
 As of the 0.11 release, IPython works with either Python 2.5 or 2.6.  
-Versions 0.9 and 0.10 worked with Python 2.4 as well.  We have not begun
-the test and port IPython to 3.0.  Our plan is to gradually drop Python 2.5
-support and then begin the transition to strict 2.6 and 3.0.
+Versions 0.9 and 0.10 worked with Python 2.4 as well.  We have not yet begun
+to test and port IPython to Python 3.  Our plan is to gradually drop Python 2.5
+support and then begin the transition to strict 2.6 and 3.
 
 IPython is known to work on the following operating systems:
 

docs/source/whatsnew/index.txt

@@ -12,6 +12,11 b''
 What's new in IPython
 =====================
 
+This section documents the changes that have been made in various versions of
+IPython. Users should consult these pages to learn about new features, bug
+fixes and backwards incompatibilities. Developers should summarize the
+development work they do here in a user friendly format.
+
 .. toctree::
    :maxdepth: 1