Documentation

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 document/documentation/CMakeLists.txt. Most of the narrative content is stored in Markdown files in the document/documentation 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 containing 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, and use this command to serve the result:

# Replace lue_build by the directory containing the LUE build files
python3 -m http.server -d lue_build/document/documentation/_build/html

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 document/documentation directory in the build directory, reconfiguring the project (cmake .), and then rebuilding the documentation (cmake --build . --target documentation).

Reference pages#

The reference section is an important part of the LUE documentation. It contains the operation pages, each describing a single LUE framework operation.

Operation page#

An operation page describes, possible multiple overloads of, a single LUE operation. Each page contains the same set of sections:

Signature
Description
No-data handling
Example
See also

Sections#

Signature#

A signature for each overload of the operation, in a language agnostic way.

Description#

The description of the operation, in a language agnostic way. If needed the description should highlight differences between overloads.

No-data handling#

A description of how no-data values are handled by the operation. After reading this section, the user of the operation must understand how the operation deals with no-data values in the arguments, and under what circumstances no-data is generated and written to the result.

Example#

One or more language-specific examples of calling and operation. Per example, an implementation must be provided for all supported programming languages.

Add a new page#

Use a similar operation for inspiration:
- Copy and rename its Markdown file, replace its contents. Add new file to documentation/CMakeLists.txt and documentation/_toc.yml.
- Copy and rename its example directory. Update its CMakeLists.txt and the source code.
Rebuild the documentation and inspect the message printed and the resulting HTML. Running a local web server can by handy for this:
```
python -m http.server $lue_build_directory/document/documentation/_build/html
```