docs/dev-manual/documentation-generation.rst

   1 Documentation generation
   2 ========================
   3
   4 Building the |Gromacs| documentation
   5 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   6
   7 For now, there are multiple components, formats and tools for the
   8 |Gromacs| documentation, which is aimed primarily at version-specific
   9 deployment of the complete documentation on the website and in the
  10 release tarball.
  11
  12 This is quite complex, because the dependencies for building the
  13 documentation must not get in the way of building the code
  14 (particularly when cross-compiling), and yet the code must build and
  15 run in order for some documentation to be generated. Also, man page
  16 documentation (and command-line completions) must be built from the
  17 wrapper binary, in order to be bundled into the tarball. This helps
  18 ensure that the functionality and the documentation remain in sync.
  19
  20 The outputs of interest to most developers are generally produced in the
  21 ``docs/html/`` subdirectory of the build tree.
  22
  23 You need to enable at least some of the following CMake options:
  24
  25 ``GMX_BUILD_MANUAL``
  26   Option needed for trying to build the PDF reference manual
  27   (requires LaTeX and ImageMagick). See :cmake:`GMX_BUILD_MANUAL`.
  28 ``GMX_BUILD_HELP``
  29   Option that controls 1) whether shell completions are built automatically,
  30   and 2) whether built man pages are installed if available (the user still needs
  31   to build the ``man`` target manually before installing). See
  32   :cmake:`GMX_BUILD_HELP`.
  33
  34 Some documentation cannot be built if the CMake option
  35 ``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it
  36 requires executing the ``gmx`` binary.
  37
  38 The following make targets are the most useful:
  39
  40 ``manual``
  41   Builds the PDF reference manual.
  42 ``man``
  43   Makes man pages from the wrapper binary with Sphinx.
  44 ``doxygen-all``
  45   Makes the code documentation with Doxygen.
  46 ``install-guide``
  47   Makes the INSTALL file for the tarball with Sphinx.
  48 ``webpage-sphinx``
  49   Makes all the components of the |Gromacs| webpage that require Sphinx,
  50   including install guide and user guide.
  51 ``webpage``
  52   Makes the complete |Gromacs| webpage, requires everything. When complete,
  53   you can browse ``docs/html/index.html`` to find everything.
  54
  55   If built from a release tarball, the ``SOURCE_MD5SUM``,
  56   ``SOURCE_TARBALL``, ``REGRESSIONTESTS_MD5SUM``, and
  57   ``REGRESSIONTESTS_TARBALL`` CMake variables can be set to pass in
  58   the md5sum values and names of those tarballs, for embedding into the
  59   final deployment to the |Gromacs| website.
  60
  61 Needed build tools
  62 ^^^^^^^^^^^^^^^^^^
  63
  64 The following tools are used in building parts of the documentation.
  65
  66 Doxygen
  67   `Doxygen <http://www.doxygen.org>`_ is used to extract documentation from
  68   source code comments.  Also some other overview
  69   content is laid out by Doxygen from Markdown source files.  Currently, version
  70   |EXPECTED_DOXYGEN_VERSION| is required for a warning-free build.  Thorough
  71   explanation of the Doxygen setup and instructions for documenting the source
  72   code can be found on a separate page: :doc:`doxygen`.
  73
  74 graphviz (dot)
  75   The Doxygen documentation uses ``dot`` from `graphviz
  76   <http://www.graphviz.org>`_ for building some graphs.  The tool is not
  77   mandatory, but the Doxygen build will produce warnings if it is not
  78   available, and the graphs are omitted from the documentation.
  79
  80 mscgen
  81   The Doxygen documentation uses `mscgen
  82   <http://www.mcternan.me.uk/mscgen/>`_ for building some graphs.  As with ``dot``,
  83   the tool is not mandatory, but not having it available will result in warnings
  84   and missing graphs.
  85
  86 Doxygen issue checker
  87   Doxygen produces warnings about some incorrect uses and wrong
  88   documentation, but there are many common mistakes that it does not detect.
  89   |Gromacs| uses an additional, custom Python script to check for such issues.
  90   This is most easily invoked through a ``check-source`` target in the build system.
  91   The script also checks that documentation for a header matches its use in the
  92   source code (e.g., that a header documented as internal to a module is not
  93   actually used from outside the module).  These checks are run in Jenkins as
  94   part of the Documentation job.  Details for the custom checker are on a
  95   separate page (common for several checkers): :doc:`gmxtree`.
  96
  97 module dependency graphs
  98   |Gromacs| uses a custom Python script to generate an annotated dependency
  99   graph for the code, showing #include dependencies between modules.
 100   The generated graph is embedded into the Doxygen documentation:
 101   `Module dependency graph`__
 102   This script shares most of its implementation with the custom checkers, and is
 103   documented on the same page: :doc:`gmxtree`.
 104
 105 __ doxygen-page-modulegraph_
 106
 107 Sphinx
 108   `Sphinx <http://sphinx-doc.org/>`_; at least version |EXPECTED_SPHINX_VERSION| is used
 109   for building some parts of the documentation from reStructuredText
 110   source files.
 111
 112 LaTeX
 113   Also requires ImageMagick for converting graphics file formats.
 114
 115 linkchecker
 116   The linkchecker program is used together with the linkcheckerrc file to ensure
 117   that all the links in the documentation can be resolved correctly.
 118
 119 documentation exported from source files
 120   For man pages, HTML documentation of command-line options for executables,
 121   and for shell completions, the ``gmx`` binary has explicit C++ code to export
 122   the information required.  The build system provides targets that then invoke
 123   the built ``gmx`` binary to produce these documentation items.  The generated
 124   items are packaged into source tarballs so that this is not necessary when
 125   building from a source distribution (since in general, it will not work in
 126   cross-compilation scenarios).  To build and install these from a git
 127   distribution, explicit action is required.
 128   See `Doxygen documentation on the wrapper binary`__
 129   for some additional details.
 130
 131 __ doxygen-page-wrapperbinary_
 132
 133 .. include:: /fragments/doxygen-links.rst