[IPython-dev] IPython documentation

[Brian Granger]

Hello all,

So, I have finished merging in the ipython1 documentation into IPython
proper.  Now all the docs are in one place.

In addition to doing this merge, I have taken the liberty of
completely reorganizing the docs.  Previously, the IPython docs were a
single rst file, which was really awkward and didn't take advantage of
Sphinx's nice features.  In the process of doing all this, I realized
that the IPython docs (not the parallel computing stuff) need quite a
bit of care and attention.  I would like to see if we can get people
to put in time to get our docs back up to where they should be.  Here
is what I am thinking:

The docs are now organized into the following sections (these are
either files or subdirectories in docs/source):

Introduction
Installation
Using IPython for interactive work
Using IPython for parallel computing
Configuration and customization
What's new
Development
Frequently asked questions
History
License and Copyright
Credits

Each of these sections needs someone to go through it and do the
following things:

1) Read through and make sure that the content is up to date and
correct.  For some sections this will be a lot of work.  For example,
because of the ipython1 -> IPython merge, our installation docs are
completely outdated.

2) Make sure that all the internal links are working correctly.  For
this we are using Shinx's "ref" capability.  See the Sphinx docs for
more details.  In some cases, this will require that you make new
labels for things.

If people need doc-writing inspiration check out your favorite well
documented project.  Some of my favorites are django and sqlalchemy.

The good news is that we now have lots of docs.  The bad news is that
I can't do all of this myself.  I can take the following sections
though:

Installation
Using IPython for parallel computing
Development

If you are interested in helping improve our docs, let us know and we
will figure out the best way for you to contribute.  Some of the
sections will probably need to be worked on by specific people.  But
we can surely find a way for eager people to help out.

Cheers,

Brian