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 https://www.python.org/. Both Mac and Windows users will need to install a version of Latex: Mac: https://www.tug.org/mactex/ Windows: https://miktex.org/ To install sphinx on Mac OS X, go to Terminal and type:
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: https://pypi.org/project/setuptools/. If you have trouble installing that, Michael found this link to be helpful: https://stackoverflow.com/questions/309412/how-do-i-set-up-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 ../..