Fix wrong IP address for proxyout
[cacert-infradocs.git] / docs / 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 To build this documentation you need a Python 3 installation. To isolate the
10 documentation build from your system Python 3 packages using a virtual
11 environment is recommended.
12
13 Python 3 installation instructions can be found on the `Python website`_.
14
15 .. _Python website: https://www.python.org/
16
17 .. topic:: Building the documentation on a Debian system
18
19 The following example shows how to build the documentation on a Debian system:
20
21 .. code-block:: bash
22
23 # Install required operating system packages
24 sudo apt-get install python3 python3-venv make
25 # Setup a fresh virtual Python environment in the venv subdirectory
26 pyvenv venv
27 # Activate the virtual environment
28 . venv/bin/activate
29 # Install the documentation build dependencies (Sphinx, extensions and
30 # their dependencies)
31 pip install -r doc-requirements.txt
32 # Build the documentation in the docs subdirectory
33 cd docs
34 make html
35
36 .. note::
37
38 The above commands should be run from the root directory of a git clone
39 of the cacert-infradocs git repository. The result of the :program:`make`
40 exection will be available in the :file:`_build/html/` directory inside
41 the :file:`docs/` directory.
42
43 Getting the documentation source
44 --------------------------------
45
46 The documentation is available from the git repository cacert-infradocs on
47 git.cacert.org. You can browse the `repository
48 <http://git.cacert.org/gitweb/?p=cacert-infradocs.git;a=summary>`_ via gitweb.
49
50 You can clone the repository anonymously by executing::
51
52 git clone git://git.cacert.org/cacert-infradocs.git
53
54 If you want to contribute to the documentation please ask git-admin@cacert.org
55 to setup a user in the group git-infra on git.cacert.org for you. You will have
56 to provide an SSH public key (either RSA with at least 2048 Bits modulus or an
57 ECDSA or ED25519 key with similar strength) with your request.
58
59 If you have a user in the git-infra group you can clone the repository by
60 executing::
61
62 git clone ssh://<username>@git.cacert.org/var/cache/git/cacert-infradocs.git
63
64 .. note:: replace ``<username>`` with your actual username
65
66 Continuous integration
67 ----------------------
68
69 If changes are pushed to the cacert-infradocs git repository on git.cacert.org
70 a `Jenkins Job <https://jenkins.cacert.org/job/cacert-infradocs/>`_ is
71 automatically triggered. If the documentation is built successfully it can be
72 viewed in the `docs/_build/html directory of the Job's workspace
73 <https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/>`_. You may
74 open `index.html
75 <https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/index.html>`_
76 to browse the documentation (there are some JavaScript and SVG glitches due to
77 Content-Security-Policy settings).
78
79 If the documentation build is successful the result is pushed to a webserver
80 document root on :doc:`webstatic` and is publicly available at
81 https://infradocs.cacert.org/.