Building the documentation

This documentation is maintained as a set of ReStructuredText documents and uses Sphinx to build HTML formatted representations of the documents.

To build this documentation you need a Python 3 installation. To isolate the documentation build from your system Python 3 packages using a virtual environment is recommended. Management of the virtual environment can be done with pipenv as described below.

Python 3 installation instructions can be found on the Python website.

Getting the documentation source

The documentation is available from the git repository cacert-infradocs on You can browse the repository via gitweb.

You can clone the repository anonymously by executing:

git clone git://

If you want to contribute to the documentation please ask to setup a user in the group git-infra on for you. You will have to provide an SSH public key (either RSA with at least 2048 Bits modulus or an ECDSA or ED25519 key with similar strength) with your request.

If you have a user in the git-infra group you can clone the repository by executing:

git clone ssh://<username>


replace <username> with your actual username

Continuous integration

If changes are pushed to the cacert-infradocs git repository on a Jenkins Job is automatically triggered. If the documentation is built successfully it can be viewed in the docs/_build/html directory of the Job’s workspace. You may open index.html to browse the documentation (there are some JavaScript and SVG glitches due to Content-Security-Policy settings).

If the documentation build is successful the result is pushed to a webserver document root on Webstatic and is publicly available at


The .sshkeys Sphinx directive for a system can be generated using this shell snippet:

echo '.. sshkeys::' ; for k in /etc/ssh/ssh_host_*pub; do echo -n '   ' ; (a=$(echo :${${$(basename $k)##ssh_host_}/}: | tr '[:lower:]' '[:upper:]'); echo $a; ssh-keygen -E SHA256 -l -f $k|cut -d ' ' -f 2; ssh-keygen -E MD5 -l -f $k|cut -d ' ' -f 2) | tr '\n' ' ' ; echo; done