You are here

Sphinx

Primary tabs

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 ../..