# 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

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


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