Fix inaccuracy in signer protocol specification
[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 There is a github mirror of this repository available at
20
21 https://github.com/CAcertOrg/cacert-codedocs
22
23 You make fork from that clone and contribute your changes via pull requests.
24 Merged pull requests will be applied to the repository at git.cacert.org.
25
26 If you just want to contribute to the documentation you are encouraged to use
27 Github and pull requests.
28
29 Please ask git-admin@cacert.org to setup a user in the group git-doc on
30 git.cacert.org for you to get push access to the git.cacert.org repository.
31 You will have to provide an SSH public key (either RSA with at least 2048 Bits
32 modulus or an ECDSA or ED25519 key with similar strength) with your request.
33
34 If you have a user in the git-doc group you can clone the repository by
35 executing::
36
37 git clone ssh://<username>@git.cacert.org/var/cache/git/cacert-codedocs.git
38
39 .. note:: replace ``<username>`` with your actual username
40
41 Building with Sphinx
42 --------------------
43
44 To build this documentation you need a Python 3 installation. To isolate the
45 documentation build from your system Python 3 packages using a virtual
46 environment is recommended. Management of the virtual environment can be done
47 with pipenv as described below.
48
49 Python 3 installation instructions can be found on the `Python website`_.
50
51 .. _Python website: https://www.python.org/
52
53 .. topic:: Building the documentation on a Debian system
54
55 The following example shows how to build the documentation on a Debian system:
56
57 .. code-block:: bash
58
59 # Install required operating system packages
60 sudo apt-get install python3 python3-pip make
61 # install pipenv
62 python3 -m pip install -U pip pipenv
63 # use pipenv to install require dependencies into a virtual environment
64 pipenv install
65 # Build the documentation
66 pipenv run make html
67
68 .. note::
69
70 You may need to add :file:`~/.local/bin` to the :envvar:`$PATH`
71 environment variable before you will be able to run :program:`pipenv`.
72 You can do this by adding ``export PATH=~/.local/bin:$PATH`` to your
73 shell initialization file like :file:`~/.bashrc` or :file:`~/.zshrc`.
74
75 The above commands should be run from the root directory of a git clone
76 of the cacert-codedocs git repository. The result of the :program:`make`
77 exection will be available in the :file:`build/html/` directory
78 directory.
79
80 Continuous integration
81 ----------------------
82
83 If changes are pushed to the cacert-codedocs git repository on git.cacert.org
84 a `Jenkins Job <https://jenkins.cacert.org/job/cacert-codedocs/>`_ is
85 automatically triggered. If the documentation is built successfully it can be
86 viewed in the `docs/_build/html directory of the Job's workspace
87 <https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/>`_. You may
88 open `index.html
89 <https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/index.html>`_
90 to browse the documentation (there are some JavaScript and SVG glitches due to
91 Content-Security-Policy settings).
92
93 If the documentation build is successful the result is pushed to a webserver
94 document root on :doc:`infradocs:systems/webstatic` and is publicly available at
95 https://codedocs.cacert.org/.