Writing Documentation

Hephaestus is using sphinx+breathe to generate its documentation. The documentation generation is done via bazel.

In order to build the documentation invoke the following command:

bazel build docs

This will generate the full documentation but might take some time due to the C++ API doxygen comment extraction.

To allow for faster iteration, there is an additional target which excludes the API docs:

bazel build docs-fast

To get a live preview of the documentation use the following:

bazel run docs.serve      # Get live preview of everything
bazel run docs-fast.serve # Get live preview without the C++ API reference

Module Documentation

We are using reStructuredText. The documentation of a module is done via doc/<module>.rst. Make sure that this document is referenced in the respective toctree of doc/index.rst.

In addition, you can add C++ API reference documentation. This is done with the help of Breathe. To include your library documentation, add it it to the heph_cc_api_doc call in the top level BUILD file. To reference an entity of the reference documentation, use Breathe Domains.

Documentation tooling

The tooling is provided by pypi managed by bazel. In order to add new tooling related dependencies, you need to add your pip package to requirements.in and update the lock file:

bazel run python_requirements.update

After having executed these steps, the newly updated packages are used in the next build invocation.