Documentation#
These documentation pages are generated by a set of tools:
Doxygen: For extracting documentation from C++ code. This documentation ends up in an XML file.
Breathe: For integrating the Doxygen output stored in the XML file with documentation generated by Sphinx.
Sphinx: For extracting documentation from Python code.
Jupyter Book: For creating the final documentation.
The process is managed by the CMake logic in documentation/doc/CMakeLists.txt. Most of the narrative
content is stored in Markdown files in the documentation/doc directory and its subdirectories. Documentation
related to source code is stored in the files containing the source code (API documentation) and in doc
subdirectories scattered in the source tree rooted at source. The idea is to put the documentation as close
to the source it documents as possible.
The CMakeLists.txt file copies all files needed for Jupyter Book to generate the documentation pages to the
build directory. When needed targets and other files will be made up to date first.
The target for building the documentation is called documentation, so this is how you can build the
documentation locally:
cmake --build . --target documentation
While updating the documentation it may be useful to serve the documentation using an http server and have the
documentation rebuild whenever needed. For that there is the environment/script/serve_documentation.py
script:
# Replace lue_source and lue_build by the directories of the LUE source and build files
serve_documentation.py lue_source lue_build
The serve_documentation.py script is not perfect. Don’t hesitate to improve it if you see an opportunity.
As an alternative, you can also regenerate the documentation “by hand” regularly.
Depending on the changes made, the generate documentation pages may not look right. This happens especially
when the table of contents is updated. In that case, the first thing to try is to remove the
documentation/doc directory in the build directory, reconfiguring the project (cmake .), and finally
rebuilding the documentation (cmake --build . --target documentation).