e3faeaefe88ea997f7c62a58d6e67e5b32909f18
[cacert-codedocs.git] / source / building.rst
1 ==========================
2 Building the documentation
3 ==========================
4
5 This documentation is maintained as a set of ReStructuredText documents and
6 uses `Sphinx <http://www.sphinx-doc.org/>`_ to build HTML formatted
7 representations of the documents.
8
9 Getting the documentation source
10 --------------------------------
11
12 The documentation is available from the git repository cacert-codedocs on
13 git.cacert.org. You can browse the :cacertgit:`cacert-codedocs` via gitweb.
14
15 You can clone the repository anonymously by executing::
16
17 git clone git://git.cacert.org/cacert-codedocs.git
18
19 If you want to contribute to the documentation please ask git-admin@cacert.org
20 to setup a user in the group git-doc on git.cacert.org for you. You will have
21 to provide an SSH public key (either RSA with at least 2048 Bits modulus or an
22 ECDSA or ED25519 key with similar strength) with your request.
23
24 If you have a user in the git-doc group you can clone the repository by
25 executing::
26
27 git clone ssh://<username>@git.cacert.org/var/cache/git/cacert-codedocs.git
28
29 .. note:: replace ``<username>`` with your actual username
30
31 Building with Sphinx
32 --------------------
33
34 To build this documentation you need a Python 3 installation. To isolate the
35 documentation build from your system Python 3 packages using a virtual
36 environment is recommended. Management of the virtual environment can be done
37 with pipenv as described below.
38
39 Python 3 installation instructions can be found on the `Python website`_.
40
41 .. _Python website: https://www.python.org/
42
43 .. topic:: Building the documentation on a Debian system
44
45 The following example shows how to build the documentation on a Debian system:
46
47 .. code-block:: bash
48
49 # Install required operating system packages
50 sudo apt-get install python3 python3-pip make
51 # install pipenv
52 python3 -m pip install -U pip pipenv
53 # use pipenv to install require dependencies into a virtual environment
54 pipenv install
55 # Build the documentation
56 pipenv run make html
57
58 .. note::
59
60 The above commands should be run from the root directory of a git clone
61 of the cacert-codedocs git repository. The result of the :program:`make`
62 exection will be available in the :file:`build/html/` directory
63 directory.
64
65 Continuous integration
66 ----------------------
67
68 If changes are pushed to the cacert-codedocs git repository on git.cacert.org
69 a `Jenkins Job <https://jenkins.cacert.org/job/cacert-codedocs/>`_ is
70 automatically triggered. If the documentation is built successfully it can be
71 viewed in the `docs/_build/html directory of the Job's workspace
72 <https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/>`_. You may
73 open `index.html
74 <https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/index.html>`_
75 to browse the documentation (there are some JavaScript and SVG glitches due to
76 Content-Security-Policy settings).
77
78 If the documentation build is successful the result is pushed to a webserver
79 document root on :doc:`infradocs:systems/webstatic` and is publicly available at
80 https://codedocs.cacert.org/.