It has been decided to use Sphinx as our official documentation engine. This will allow the same documentation to be written using reStructuredText and rendered as both HTML and Latex/PDF/ps, while keeping both looking nice. Features we especially like include code inclusion, syntax highlighting, and pretty printing of math in both latex AND the browser. We'll get a setup on SVN next week at which point those working on official documentation will be able to make changes.

You can view documentation for Sphinx at

http://sphinx.pocoo.org/

It's written in Python, so, Windows users, you'll need to install that at

http://python.org

Both Mac and Windows users will need to install a version of Latex:

Mac: http://www.tug.org/mactex/
Windows: http://miktex.org/

To install sphinx on Mac OS X, go to Terminal and type (without the >):

> sudo easy_install -U sphinx

For windows users, you'll need to run this in a command prompt (maybe with admin privileges) :

> easy_install -U sphinx

Windows users, you might need to install setuptools as well:

http://pypi.python.org/pypi/setuptools

If you have trouble installing that, Michael found this link to be helpful:

http://stackoverflow.com/questions/309412/how-to-setup-setuptools-for-py...

If you want to create a test install and try it out, you can use my current workflow as follows:

> mkdir sphinx_test; cd sphinx_test
> sphinx_quickstart

It'll start asking you questions like project name, authors, etc. So far, when a question is asked with a default value (in brackets), I've selected all the defaults (by pressing return) except:

todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: 
> y
pngmath: include math, rendered as PNG images (y/N) [n]: 
> y

When complete, edit your index.rst file as desired and then:

> make html
> open _build/html/index.html
> make latex
> cd _build/latex; make all-pdf
> open *.pdf
> cd ../..