Building the Documentation¶
Please familiarize yourself with our Git Workflow before attempting to add to or build the docs yourself. If you are not, there is a high probability that you will break something, or just get frustrated.
Make sure you are on the
gh-pagesbranch. Changes to the docs source should have been merged into this branch from develop.
Adding documentation source code to the gh-pages branch means that the gh-pages branch will need to be merged with develop. Failure to do so dramatically increases the likelihood of a merge conflict somewhere down the line, since the gh-pages will contain
Configure the roadrunner cmake system using the
This basically will run the commands needed for running doxygen and sphinx.
cmake -DCMAKE_INSTALL_PREFIX=../install-mac-rel \ -DRR_DEPENDENCIES_INSTALL_PREFIX=/Users/ciaranwelsh/Documents/libroadrunner-deps/install-clang13-rel \ -DLLVM_INSTALL_PREFIX=/Users/ciaranwelsh/Documents/llvm-13.x/llvm-13.x-clang11.0.3-x64-release \ -DBUILD_TESTS=ON \ -DPython_ROOT_DIR=/Users/ciaranwelsh/miniconda3/envs/py39 \ -DBUILD_PYTHON=ON \ -DSWIG_EXECUTABLE=/Users/ciaranwelsh/Documents/swig-4.0.2/swig \ -DBUILD_DOCS=ON \ -DSPHINX_EXECUTABLE=/Users/ciaranwelsh/miniconda3/envs/py39/bin/sphinx-build cmake --build . --target roadrunner-docs-sphinx --config Release
Github hosts our documentation. It does so off of the gh-pages branch, and specifically the <roadrunner-root>/docs subfolder. The homepage of our documentation is the index.html of the docs subfolder, but this only redirects to <roadrunner-root>/docs/docs-build/index.html. Therefore, the docs-build folder is where all the action happens. When you build the roadrunner-docs-sphinx target, you are using Python’s Sphinx library to create a documentation website (using sphinx-build) and storing it in the docs-build directory, which is served as a website by github.
Because our documentation is hosted on the gh-pages branch, care must be taken with version control when updating the documentation. Specifically, you should commit documentation source code to your feature branch and this should gradually make its way to the gh-pages branch after merging with develop. Please see our Git Workflow page if any of this sounds unfamiliar.
Roadrunner is a C++ library with a C and Python front end. The C and C++ code is documented using the standard
doxygen tool, whilst the Python front end is documented using
Sphinx. Furthermore, we make use of a
Python package called Breathe for bridging the gap between
Sphinx which are the two standard documentation systems for C/C++ and Python respectively.
doxygen reads the docstrings from C/C++ code and saves them to XML which is pulled into documentation
that can be rendered by
Sphinx using directives from
Breathe. Whilst rendering the documentation
into html is handled by sphinx, we still maintain and provide access to the doxygen generated documentation.
- When roadrunner is built with the
-DBUILD_DOCS=ONflag, two new cmake targets are presented to the developer:
roadrunner-docs-sphinx target depends on the
roadrunner-docs-doxygen target, cmake will always
make sure to build the
roadrunner-docs-doxygen target before it builds the
- You will need Sphinx, Doxygen and some python packages
pip install sphinx breathe sphinxcontrib-bibtex sphinx-tabs sphinx_rtd_theme
Make sure you either install doxygen in a default location (i.e. already on the PATH) or that you add the path to the doxygen executable to the PATH environment variable so cmake can find it.
Sometimes cmake finds a different version of Python installed on your system compared to what you were expecting. Therefore, if cmake complains that it cannot locate “sphinx-build” you can provide this manually with:
Make sure that this sphinx-build is from the same python version you are using to build roadrunner.
This is particularly important when building with conda. You can control which version
of Python is found by using
-DPython_ROOT_DIR=/full/path/to/python/root. For example, if you want
to use the python inside the conda environment here at
then the Python executable is located at:
and its root is