Documentation development and contribution

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

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:

  1. Launch command in the doc_build directory created on previous step:

    make core_doxygen
    
  2. 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:

  1. Finish Getting started to get Sphinx and additional extensions.

  2. Launch documentation build:

    # From theCore directory
    mkdir doc_build
    cd doc_build
    cmake ../doc
    make core_sphinx
    
  3. 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.