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.
  77
  78 .. todo:: publish the generated documentation to some canonical place