Building the Documentation

This section is concerned with building and deploying the Documentation you are currently reading.

Prerequisite

Serialbox requires doxygen and sphinx. As sphinx imports the Python module of Serialbox to obtain the doc-strings, we require the Python3 version of sphinx. In Ubuntu (16.04), the following installs the necessary packages:

$ sudo apt-get install doxygen python3-sphinx

To enable the documentation, configure the project with the CMake variable SERIALBOX_DOCUMENTATION set to ON:

$ cmake -DSERIALBOX_DOCUMENTATION=ON ../

As mentioned, sphinx imports the Python module and thus Serialbox should be built with SERIALBOX_ENABLE_PYTHON=ON (which is default).

Building

If CMake was able to pick up doxygen and sphinx, it will provide a docs target:

$ make docs

This will install the documentation into docs/sphinx/_build/html and you can immedialtly view it by opening docs/sphinx/_build/html/index.html in your favorite browser.

Deploying

GitHub provides the ability to upload your website to GitHub Pages. To to this, we need to push the website to the gh-pages branch. The script tools/deploy-docs.sh does exactly this, meaning: Cloning the branch gh-pages, copying the website from docs/sphinx/_build/html/ and commiting and pushing the changes to your remote. To ease the burden, CMake was configured to provide a target to invoke the script:

$ make deploy-docs

To view your website, head to http://username.github.io/serialbox2 . You may need to adjust the GitHub settings of your Serialbox repository: "Settings" -> "GitHub Pages" set the "Source" to "gh-pages branch" to enable GitHub Pages.