tdocumentation.rst - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
(HTM) git clone git://src.adamsgaard.dk/pism
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
tdocumentation.rst (3096B)
---
1 .. include:: ../global.txt
2
3 .. _sec-install-documentation:
4
5 Rebuilding PISM documentation
6 =============================
7
8 You might want to rebuild the documentation from source, as PISM and its documentation
9 evolve together. These tools are required:
10
11 .. list-table::
12 :header-rows: 1
13
14 * - Tool
15 - Comment
16 * - Sphinx_
17 - needed to rebuild this Manual
18 * - sphinxcontrib.bibtex_
19 - needed to rebuild this Manual and the documentation of PISM's Python bindings
20 (below)
21 * - LaTeX_
22 - needed to rebuild the PDF version of this Manual, the |pism-browser|, and the
23 documentation of PISM's Python bindings
24 * - ``dvipng``
25 - needed to rebuild the documentation of PISM's Python bindings
26 * - Latexmk_
27 - needed to rebuild the PDF version of this Manual
28 * - doxygen_
29 - required to rebuild the |pism-browser|
30 * - graphviz_
31 - required to rebuild the |pism-browser|
32
33
34 On a Debian-based system you may be able to install these by running
35
36 .. literalinclude:: code/install_docu_libraries.sh
37 :language: bash
38 :lines: 3-
39
40 .. only:: html
41
42 Click :download:`here <code/install_docu_libraries.sh>` to download this file.
43
44 (You may need to change this command to match your package system.)
45
46 Note that if you install Sphinx using MacPorts_, you will install a version that
47 corresponds to your Python version, and its executables will have names with suffixes
48 corresponding to this version, e.g. ``sphinx-build-2.7`` rather than ``sphinx-build`` for
49 Python 2.7. You will want to set up aliases so that the standard names work as well. To do
50 this, run
51
52 .. code-block:: none
53
54 sudo port select sphinx py27-sphinx
55
56 (replacing ``py27-sphinx`` with ``py26-sphinx`` for Python 2.6, etc.) If you opt not to do
57 this, you can tell CMake the name of your Sphinx executable using
58
59 .. code-block:: none
60
61 cmake -DSPHINX_EXECUTABLE=sphinx-build-2.7 ...
62
63 for example.
64
65
66 Manual
67 ------
68
69 To rebuild this manual, change to the PISM build directory and run
70
71 .. code-block:: bash
72
73 make manual_html # for the HTML version of the manual
74 make manual_pdf # for the PDF version of the manual
75
76 The main page for this manual is then in ``doc/sphinx/html/index.html`` inside your build
77 directory.
78
79 The PDF manual will be in ``doc/sphinx/pism_manual.pdf`` in your build directory.
80
81 Source Code Browser
82 -------------------
83
84 To rebuild the |pism-browser|, change to the PISM build directory and run
85
86 .. code-block:: bash
87
88 make browser
89
90 The main page for the documentation is then in ``doc/browser/html/index.html`` inside
91 your build directory.
92
93 Re-building documentation without PISM's prerequisites
94 ------------------------------------------------------
95
96 To build documentation on a system without PISM’s prerequisite libraries (such as MPI and
97 PETSc), assuming that PISM sources are in ``~/pism-stable``, do the following:
98
99 .. code-block:: bash
100
101 cd ~/pism-stable
102 mkdir doc-build # create a build directory
103 cd doc-build
104 cmake ../doc
105
106 then commands "``make manual_html``", "``make manual_pdf``" and others (see above) will
107 work as expected.