You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
96 lines
3.7 KiB
ReStructuredText
96 lines
3.7 KiB
ReStructuredText
==========================
|
|
Building the documentation
|
|
==========================
|
|
|
|
This documentation is maintained as a set of ReStructuredText documents and
|
|
uses `Sphinx <http://www.sphinx-doc.org/>`_ to build HTML formatted
|
|
representations of the documents.
|
|
|
|
Getting the documentation source
|
|
--------------------------------
|
|
|
|
The documentation is available from the git repository cacert-codedocs on
|
|
git.cacert.org. You can browse the :cacertgit:`cacert-codedocs` via gitweb.
|
|
|
|
You can clone the repository anonymously by executing::
|
|
|
|
git clone git://git.cacert.org/cacert-codedocs.git
|
|
|
|
There is a github mirror of this repository available at
|
|
|
|
https://github.com/CAcertOrg/cacert-codedocs
|
|
|
|
You make fork from that clone and contribute your changes via pull requests.
|
|
Merged pull requests will be applied to the repository at git.cacert.org.
|
|
|
|
If you just want to contribute to the documentation you are encouraged to use
|
|
Github and pull requests.
|
|
|
|
Please ask git-admin@cacert.org to setup a user in the group git-doc on
|
|
git.cacert.org for you to get push access to the git.cacert.org repository.
|
|
You will have to provide an SSH public key (either RSA with at least 2048 Bits
|
|
modulus or an ECDSA or ED25519 key with similar strength) with your request.
|
|
|
|
If you have a user in the git-doc group you can clone the repository by
|
|
executing::
|
|
|
|
git clone ssh://<username>@git.cacert.org/var/cache/git/cacert-codedocs.git
|
|
|
|
.. note:: replace ``<username>`` with your actual username
|
|
|
|
Building with Sphinx
|
|
--------------------
|
|
|
|
To build this documentation you need a Python 3 installation. To isolate the
|
|
documentation build from your system Python 3 packages using a virtual
|
|
environment is recommended. Management of the virtual environment can be done
|
|
with pipenv as described below.
|
|
|
|
Python 3 installation instructions can be found on the `Python website`_.
|
|
|
|
.. _Python website: https://www.python.org/
|
|
|
|
.. topic:: Building the documentation on a Debian system
|
|
|
|
The following example shows how to build the documentation on a Debian system:
|
|
|
|
.. code-block:: bash
|
|
|
|
# Install required operating system packages
|
|
sudo apt-get install python3 python3-pip make
|
|
# install pipenv
|
|
python3 -m pip install -U pip pipenv
|
|
# use pipenv to install require dependencies into a virtual environment
|
|
pipenv install
|
|
# Build the documentation
|
|
pipenv run make html
|
|
|
|
.. note::
|
|
|
|
You may need to add :file:`~/.local/bin` to the :envvar:`$PATH`
|
|
environment variable before you will be able to run :program:`pipenv`.
|
|
You can do this by adding ``export PATH=~/.local/bin:$PATH`` to your
|
|
shell initialization file like :file:`~/.bashrc` or :file:`~/.zshrc`.
|
|
|
|
The above commands should be run from the root directory of a git clone
|
|
of the cacert-codedocs git repository. The result of the :program:`make`
|
|
exection will be available in the :file:`build/html/` directory
|
|
directory.
|
|
|
|
Continuous integration
|
|
----------------------
|
|
|
|
If changes are pushed to the cacert-codedocs git repository on git.cacert.org
|
|
a `Jenkins Job <https://jenkins.cacert.org/job/cacert-codedocs/>`_ is
|
|
automatically triggered. If the documentation is built successfully it can be
|
|
viewed in the `docs/_build/html directory of the Job's workspace
|
|
<https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/>`_. You may
|
|
open `index.html
|
|
<https://jenkins.cacert.org/job/cacert-codedocs/ws/build/html/index.html>`_
|
|
to browse the documentation (there are some JavaScript and SVG glitches due to
|
|
Content-Security-Policy settings).
|
|
|
|
If the documentation build is successful the result is pushed to a webserver
|
|
document root on :doc:`infradocs:systems/webstatic` and is publicly available at
|
|
https://codedocs.cacert.org/.
|