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