About the documentation

Building the documentation

To build the documentation, first install the necessary documentation python packages. These are available in docs optional dependencies:

$ pip install .[docs]

Then, to build the documentations simply run:

$ sphinx-build . ./build

For more intensive documentation editing I recommend using sphinx-autobuild which serves the generated documentation (default http://127.0.0.1:8000) and automatically rebuilds it whenever you make changes.

$ sphinx-autobuild . ./build

Documentation notes

We heavily reuse the documentation already found in the source markdown files like the installation instructions in Readme.md. See an example in install.md. Please do not use sphinx/myst_parser specific directives for these included files. Use the files in this doc folder to insert the sphinx/myst_parser specific directives.

The main cmake module documentations is found in the cmake folder. Make sure that there is a skeleton markdown files in cmake_modules folder, e.g. DynamicVersion.md.

Other personal standards applied:

• Use markdown file format only
• Use colon-fence ::: instead of triple-tick ```
• Use yaml for directive configurations