Section author: Axel Huebl, alpaka-group
In the following section we explain how to contribute to this documentation.
If you are reading the HTML version and want to improve or correct existing pages, check the “Edit on GitHub” link on the right upper corner of each document.
Alternatively, go to docs/source in our source code and follow the directory structure of reStructuredText (
.rst) files there.
For intrusive changes, like structural changes to chapters, please open an issue to discuss them beforehand.
This document is build based on free open-source software, namely Sphinx, Doxygen (C++ APIs as XML), Breathe (to include doxygen XML in Sphinx) and rst2pdf (render the cheat sheet). A web-version is hosted on ReadTheDocs.
The following requirements need to be installed (once) to build our documentation successfully:
# doxygen is not shipped via pip, install it externally,
# from the homepage, your package manager, conda, etc.
sudo apt-get install doxygen
# sudo pacman -S doxygen
# python tools & style theme
pip install -r requirements.txt # --user
With all documentation-related software successfully installed, just run the following commands to build your docs locally. Please check your documentation build is successful and renders as you expected before opening a pull request!
# skip this if you are still in docs/
# parse the C++ API documentation (default: xml format)
# render the cheatsheet.pdf
rst2pdf -s cheatsheet/cheatsheet.style source/basic/cheatsheet.rst -o cheatsheet/cheatsheet.pdf
# render the '.rst' files with sphinx
# open it, e.g. with firefox :)
# now again for the pdf :)
# open it, e.g. with okular
Run make clean to clean the build directory before executing actual make. This is necessary to reflect changes outside the rst files.
There is a checklinks target to check links in the rst files on availability:
# check existence of links
# cd docs/
The Doxyfile for doxygen is configured to output in xml format per default.
Another targets can be configured in the Doxyfile. The final documentations are stored in
# run in docs/doxygen/
sed -i -E 's/(GENERATE_HTML\s*=\s*)NO/\1YES/g' Doxyfile