Documentation development and contribution¶

theCore documentation, as you may have noticed, is hosted on GitHub pages and built using Sphinx with few extensions:

Read The Docs theme - awesome theme.

FullToc - full ToC in the sidebar.

All the documentation sources placed under doc top-level directory.

To contribute to the documentation, you probably would like to first build and validate docs locally. For that, build dependencies must be installed either manually or by using Nix. Check the Getting started for more info about Nix option.

Following sections will provide you with insights about docs structure and build procedure.

Building Doxygen documentation¶

theCore contains Doxygen and it is possible to generate Doxygen pages locally using CMake target:

Launch command in the doc_build directory created on previous step:
```
make core_doxygen
```
Open index page of generated Doxygen by any preferable browser: doc_build/doc/doxygen/html/index.html

Building Sphinx documentation¶

theCore build system provides a separate target for building documentation, so there is no need to invoke Sphinx manually. Doxygen will be built automatically before Sphinx. Proceed as follows:

Finish Getting started to get Sphinx and additional extensions.

Launch documentation build:

# From theCore directory
mkdir doc_build
cd doc_build
cmake ../doc
make core_sphinx

Open generated docs by any preferable browser:
- doc_build/sphinx/theCore/index.html - main page of multi-page version.
- doc_build/sphinx/theCore/singlehtml/index.html - main page of single-paged version.

What all these sections are about?¶

Note

This section is under construction.

Publishing docs on github pages¶

As noted previously, docs are hosted in GitHub pages. The separate repository holds auto-generated static HTML files which are automatically displayed if placed in master branch of that repo. Jekyll is disabled.

See also the GitHub pages docs for more information.

Contributing to the documentation consist of creating a PR against theCore repository.

After the PR is merged, the new documentation is deployed using scripts/doc_deploy.sh script.