Building the Documentation

All documentation and related files are located in the source tree under the doc directory. Building documentation requires enabling the build with the CMake option -DENABLE_DOCS=ON (documentation builds are disabled by default).

Additional packages required for building the documentation.

System installs

These should be installed via your system package manager (e.g., yum, dnf, apt, brew, etc.):

graphviz: Graph visualization software (provides the dot command), used for diagrams in many places.
java: A Java runtime is required to run PlantUML for generating diagrams.
python3: Python 3 is required. The build system will use this to create a virtual environment.
pipenv: Used to manage Python dependencies. Install with pip3 install pipenv or your system package manager.

Python packages

Python dependencies are managed automatically via pipenv and the doc/Pipfile. The build system will automatically create a virtual environment and install all required packages (including Sphinx, sphinx-rtd-theme, sphinxcontrib-plantuml, sphinx-intl for internationalization, and other dependencies) when you build the documentation.

You do not need to manually install these packages or set up pipenv yourself - the CMake build targets handle this automatically.

Building the documentation

With CMake configured with -DENABLE_DOCS=ON, building the documentation is straightforward:

# Configure the build (only needed once, or when changing options)
cmake -B build -DENABLE_DOCS=ON

# Build HTML documentation
cmake --build build --target generate_docs

# Build PDF documentation (Letter paper size)
cmake --build build --target generate_pdf

# Build PDF documentation (A4 paper size)
cmake --build build --target generate_pdf_a4

The build system will automatically:

Create a pipenv virtual environment in the build directory
Install all required Python packages from doc/Pipfile
Generate the documentation

For repeated builds while working on the documentation, simply run the build command again. The build system will detect what needs to be regenerated. To force a complete rebuild, you can remove the build directory and reconfigure.

注釈

It is expected that any PR updating the documentation builds without any errors or warnings. This can be easy to miss if the full build is not done before submitting the pull request.

To view the built documentation, you may point any browser to the directory doc/docbuild/html/. If you are building the documentation on your local machine, you may access the HTML documentation files directly without the need for a full-fledged web server, as all necessary resources (CSS, Javascript, and images) are referenced using relative paths and there are no server-side scripts necessary to render the documentation.