Documentation generation#
Building the GROMACS documentation#
For now, there are multiple components, formats and tools for the GROMACS documentation, which is aimed primarily at version-specific deployment of the complete documentation on the website and in the release tarball.
This is quite complex, because the dependencies for building the documentation must not get in the way of building the code (particularly when cross-compiling), and yet the code must build and run in order for some documentation to be generated. Also, man page documentation (and command-line completions) must be built from the wrapper binary, in order to be bundled into the tarball. This helps ensure that the functionality and the documentation remain in sync.
The outputs of interest to most developers are generally produced in the
docs/html/
subdirectory of the build tree.
You need to enable at least some of the following CMake options:
GMX_BUILD_MANUAL
Option needed for trying to build the PDF reference manual (requires LaTeX and ImageMagick). See
GMX_BUILD_MANUAL
.GMX_BUILD_HELP
Option that controls 1) whether shell completions are built automatically, and 2) whether built man pages are installed if available (the user still needs to build the
man
target manually before installing). SeeGMX_BUILD_HELP
.
To include the full Python package documentation with the webpage
CMake target (see below), also configure CMake with GMX_PYTHON_PACKAGE=ON
,
and install Python package dependencies from
python_packaging/gmxapi/requirements.txt
:
pip install -r python_packaging/gmxapi/requirements.txt
Some documentation cannot be built when cross-compiling, as it
requires executing the gmx
binary.
The following make targets are the most useful:
manual
Builds the PDF reference manual.
man
Makes man pages from the wrapper binary with Sphinx.
doxygen-all
Makes the code documentation with Doxygen.
install-guide
Makes the INSTALL file for the tarball with Sphinx.
webpage-sphinx
Makes all the components of the GROMACS webpage that require Sphinx, including install guide and user guide.
webpage
Makes the complete GROMACS webpage, requires everything. When complete, you can browse
docs/html/index.html
to find everything.If built from a release tarball, the
SOURCE_MD5SUM
,SOURCE_TARBALL
,REGRESSIONTESTS_MD5SUM
, andREGRESSIONTESTS_TARBALL
CMake variables can be set to pass in the md5sum values and names of those tarballs, for embedding into the final deployment to the GROMACS website.
Needed build tools#
The following tools are used in building parts of the documentation. Make sure they are installed before configuring the build system with CMake.
- Doxygen
Doxygen is used to extract documentation from source code comments. Also some other overview content is laid out by Doxygen from Markdown source files. Currently, version 1.8.5 is required for a warning-free build. Thorough explanation of the Doxygen setup and instructions for documenting the source code can be found on a separate page: Using Doxygen.
- graphviz (dot)
The Doxygen documentation uses
dot
from graphviz for building some graphs. The tool is not mandatory, but the Doxygen build will produce warnings if it is not available, and the graphs are omitted from the documentation.- mscgen
The Doxygen documentation uses mscgen for building some graphs. As with
dot
, the tool is not mandatory, but not having it available will result in warnings and missing graphs.- Doxygen issue checker
Doxygen produces warnings about some incorrect uses and wrong documentation, but there are many common mistakes that it does not detect. GROMACS uses an additional, custom Python script to check for such issues. This is most easily invoked through a
check-source
target in the build system. The script also checks that documentation for a header matches its use in the source code (e.g., that a header documented as internal to a module is not actually used from outside the module). These checks are run in CI. Details for the custom checker are on a separate page (common for several checkers): Source tree checker scripts.- module dependency graphs
GROMACS uses a custom Python script to generate an annotated dependency graph for the code, showing #include dependencies between modules. The generated graph is embedded into the Doxygen documentation: Module dependency graph This script shares most of its implementation with the custom checkers, and is documented on the same page: Source tree checker scripts.
- Sphinx
Sphinx; at least version 4.0.0 is used for building some parts of the documentation from reStructuredText source files. To install an appropriate version of
sphinx-build
and other required Python packages, you can use therequirements.txt
file in thedocs
repository directory. E.g. pip install -r docs/requirements.txt- LaTeX
Also requires ImageMagick for converting graphics file formats.
- linkchecker
linkchecker is used together with the
docs/linkcheckerrc
file to ensure that all the links in the documentation can be resolved correctly.- documentation exported from source files
For man pages, HTML documentation of command-line options for executables, and for shell completions, the
gmx
binary has explicit C++ code to export the information required. The build system provides targets that then invoke the builtgmx
binary to produce these documentation items. The generated items are packaged into source tarballs so that this is not necessary when building from a source distribution (since in general, it will not work in cross-compilation scenarios). To build and install these from a git distribution, explicit action is required. See Doxygen documentation on the wrapper binary for some additional details.