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 version 3.0 or newer

needed to rebuild this Manual

sphinxcontrib.bibtex

needed to rebuild this Manual

LaTeX

needed to rebuild the PDF version of this Manual

Latexmk

needed to rebuild the PDF version of this Manual

ncgen from NetCDF

needed to rebuild this Manual

netcdf4-python

needed to rebuild 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 most of these by running

sudo apt-get install \
     graphviz \
     texlive texlive-fonts-extra \
     latexmk

pip3 install sphinx sphinxcontrib-bibtex --user

Click here to download this file.

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

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