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-python-2-6-on-windows
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 ../..