path: root/source/building.rst
diff options
authorJan Dittberner <>2018-10-27 14:26:40 +0200
committerJan Dittberner <>2018-10-27 14:26:40 +0200
commit8ba1692ba7e8d572aa1f7fddd9b89d4316399ad6 (patch)
tree7d5645d36a06a03b551bb2dd975e9738fbbc3d62 /source/building.rst
parent844119e0863da10d94b465150cde119b848f29b8 (diff)
Add build documentation for this project
- Add intersphinx configuration for infradocs - Ensure availability of CAcert root certificates - add building.rst that describes how to get and build the documentation source code
Diffstat (limited to 'source/building.rst')
1 files changed, 81 insertions, 0 deletions
diff --git a/source/building.rst b/source/building.rst
new file mode 100644
index 0000000..f07f72d
--- /dev/null
+++ b/source/building.rst
@@ -0,0 +1,81 @@
+Building the documentation
+This documentation is maintained as a set of ReStructuredText documents and
+uses `Sphinx <>`_ to build HTML formatted
+representations of the documents.
+Getting the documentation source
+The documentation is available from the git repository cacert-codedocs on You can browse the `repository
+<;a=summary>`_ 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-doc 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-doc group you can clone the repository by
+ git clone ssh://<username>
+.. note:: replace ``<username>`` with your actual username
+Building with Sphinx
+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`_.
+.. _Python website:
+.. topic:: Building the documentation on a Debian system
+ The following example shows how to build the documentation on a Debian system:
+ .. code-block:: bash
+ # Install required operating system packages
+ sudo apt-get install python3 python3-pip make
+ # install pipenv
+ python3 -m pip install -U pip pipenv
+ # use pipenv to install require dependencies into a virtual environment
+ pipenv install
+ # Build the documentation
+ pipenv run make html
+ .. note::
+ The above commands should be run from the root directory of a git clone
+ of the cacert-codedocs git repository. The result of the :program:`make`
+ exection will be available in the :file:`build/html/` directory
+ directory.
+Continuous integration
+If changes are pushed to the cacert-codedocs 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 :doc:`infradocs:systems/webstatic` and is publicly available at