Building the Documentation

The documentation for Enzo (including this very document) is built using the reStructuredText (ReST) syntax which is parsed into final formats using the Sphinx engine. Sphinx is a python package which may be installed using the pip Python package installation tool like this:

$ pip install sphinx

Once that is installed, make sure that the binary sphinx-build is in your path ($ which sphinx-build). Relative to the top level of the Enzo package, the Enzo docs are in doc/manual. This directory contains a Makefile and a source directory. From within this directory, this command will parse the documents into a hierarchy of HTML files (identical what is on the web) into a new directory build:

$ make clean
$ make html

If that is successful, point your web browser to the file on disk (using the Open File... option of the File menu) build/html/index.html (this is relative to this same directory with the Makefile). On Mac OS X this command should work: open build/html/index.html. The docs should be nearly identical to what is online, but they are coming from the local machine.

Building a PDF of the Documentation

If (PDF)LaTeX is functional, is it possible to build a PDF of the Enzo documentation in one step. In the directory with the Makefile, use this command:

$ make latexpdf

If this is successful, the PDF will be build/latex/Enzo.pdf. The PDF might be preferred for some users, and can be searched all at once for a term, unlike a local copy of the HTML.

If PDFLaTeX is not working, $ make latex will not attempt to make the PDF. A PS or DVI (or whatever anachronistic thing your SPARCstation makes) can be made starting from build/latex/Enzo.tex.

Updating the Online Pre-Built Documentation

If you are an Enzo developer and need to update the current build of the documentation, these instructions should step you through that process. In the directory doc/manual, clone a copy of the docs repository and call it enzo-docs:

$ hg clone https://docs.enzo.googlecode.com/hg/ enzo-docs

The enzo-docs repository holds HTML and image files which are accessed over the web on the Google Code pages, and it is not modified manually.

In the directory doc/manual, execute these commands:

$ cd enzo-docs
$ hg pull
$ hg up
$ cd ..
$ rm -rf enzo-docs/*
$ make clean
$ make html
$ export CURRENT_REV="`hg identify`"
$ cp -Rv build/html/* enzo-docs/
$ cd enzo-docs
$ hg addremove --similarity=25
$ hg ci -m "Build from ${CURRENT_REV}"
$ hg push

The addremove extension will automatically update the current state of the files to be pushed with whatever is found in that directory. It will remove all files that it no longer sees and add all the files it currently does see. (You can supply --dry-run to see what it will do). The similarity argument just helps with keeping the size of the commits down, but because this repository is only to be used as a holding place for static content this should not be a problem.