documentation.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.