Rebuilding PISM documentation

You might want to rebuild the documentation from source, as PISM and its documentation evolve together. These tools are required:

Tool Comment
Sphinx needed to rebuild this Manual
sphinxcontrib.bibtex needed to rebuild this Manual and the documentation of PISM’s Python bindings (below)
LaTeX needed to rebuild the PDF version of this Manual, the PISM Source Code Browser, and the documentation of PISM’s Python bindings
dvipng needed to rebuild the documentation of PISM’s Python bindings
Latexmk needed to rebuild the PDF version of this Manual
doxygen required to rebuild the PISM Source Code Browser
graphviz required to rebuild the PISM Source Code Browser

On a debian-based system you may be able to install these by running

sudo apt-get install \
     sphinx python-sphinx \
     graphviz dvipng \
     texlive texlive-fonts-extra \
     latexmk

sudo pip install sphinxcontrib-bibtex

Click here to download this file.

(You may need to change this command to match your package system.)

Note that if you install Sphinx using MacPorts, you will install a version that corresponds to your Python version, and its executables will have names with suffixes corresponding to this version, e.g. sphinx-build-2.7 rather than sphinx-build for Python 2.7. You will want to set up aliases so that the standard names work as well. To do this, run

sudo port select sphinx py27-sphinx

(replacing py27-sphinx with py26-sphinx for Python 2.6, etc.) If you opt not to do this, you can tell CMake the name of your Sphinx executable using

cmake -DSPHINX_EXECUTABLE=sphinx-build-2.7 ...

for example.

Manual

To rebuild this manual, change to the PISM build directory and run

make manual_html # for the HTML version of the manual
make manual_pdf  # for the PDF version of the manual

The main page for this manual is then in doc/sphinx/html/index.html inside your build directory.

The PDF manual will be in doc/sphinx/pism_manual.pdf in your build directory.

Source Code Browser

To rebuild the PISM Source Code Browser, change to the PISM build directory and run

make browser

The main page for the documentation is then in doc/browser/html/index.html inside your build directory.

Re-building documentation without PISM’s prerequisites

To build documentation on a system without PISM’s prerequisite libraries (such as MPI and PETSc), assuming that PISM sources are in ~/pism-stable, do the following:

cd ~/pism-stable
mkdir doc-build # create a build directory
cd doc-build
cmake ../doc

then commands “make manual_html”, “make manual_pdf” and others (see above) will work as expected.


Previous Up Next