summaryrefslogtreecommitdiff
path: root/source
diff options
context:
space:
mode:
authorJan Dittberner <jandd@cacert.org>2018-10-27 14:26:40 +0200
committerJan Dittberner <jandd@cacert.org>2018-10-27 14:26:40 +0200
commit8ba1692ba7e8d572aa1f7fddd9b89d4316399ad6 (patch)
tree7d5645d36a06a03b551bb2dd975e9738fbbc3d62 /source
parent844119e0863da10d94b465150cde119b848f29b8 (diff)
downloadcacert-codedocs-8ba1692ba7e8d572aa1f7fddd9b89d4316399ad6.tar.gz
cacert-codedocs-8ba1692ba7e8d572aa1f7fddd9b89d4316399ad6.tar.xz
cacert-codedocs-8ba1692ba7e8d572aa1f7fddd9b89d4316399ad6.zip
Add build documentation for this project
- Add intersphinx configuration for infradocs - Ensure availability of CAcert root certificates - add building.rst that describes how to get and build the documentation source code
Diffstat (limited to 'source')
-rw-r--r--source/_static/.keep0
-rw-r--r--source/building.rst81
-rw-r--r--source/conf.py24
-rw-r--r--source/index.rst6
4 files changed, 104 insertions, 7 deletions
diff --git a/source/_static/.keep b/source/_static/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/source/_static/.keep
diff --git a/source/building.rst b/source/building.rst
new file mode 100644
index 0000000..f07f72d
--- /dev/null
+++ b/source/building.rst
@@ -0,0 +1,81 @@
+==========================
+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 `repository
+<http://git.cacert.org/gitweb/?p=cacert-codedocs.git;a=summary>`_ via gitweb.
+
+You can clone the repository anonymously by executing::
+
+ git clone git://git.cacert.org/cacert-codedocs.git
+
+If you want to contribute to the documentation please ask git-admin@cacert.org
+to setup a user in the group git-doc on git.cacert.org for you. 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::
+
+ 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/.
diff --git a/source/conf.py b/source/conf.py
index a80f538..f3750f4 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -14,10 +14,26 @@
#
from datetime import datetime
import os
+import certifi
+import requests
# import sys
# sys.path.insert(0, os.path.abspath('.'))
from git import repo
+from docutils import nodes, utils
+
+try:
+ print('Checking connection to infradocs.cacert.org')
+ requests.head('https://infradocs.cacert.org/')
+ print('Connection to infradocs.cacert.org OK')
+except requests.exceptions.SSLError as err:
+ print('SSL Error. Adding CAcert certificates to Certifi store...')
+ cafile = certifi.where()
+ with open(os.path.join(
+ os.path.dirname(__file__), '..', 'cacert.pem'), 'rb') as infile:
+ cacertca = infile.read()
+ with open(cafile, 'ab') as outfile:
+ outfile.write(cacertca)
# -- Project information -----------------------------------------------------
@@ -29,10 +45,8 @@ author = 'CAcert development team'
version = '0.1'
# The full version, including alpha/beta/rc tags
release = "{}-git:{} built:{}".format(
- version,
- repo.Repo('..').git.describe('--always', '--dirty'),
- datetime.utcnow().replace(microsecond=0))
-
+ version, repo.Repo('..').git.describe('--always', '--dirty'),
+ datetime.utcnow().replace(microsecond=0))
# -- General configuration ---------------------------------------------------
@@ -197,7 +211,7 @@ epub_exclude_files = ['search.html']
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'infradocs': ('https://infradocs.cacert.org', None)}
# -- Options for todo extension ----------------------------------------------
diff --git a/source/index.rst b/source/index.rst
index bb39a6d..e1abc94 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to CAcert code documentation
-====================================
+CAcert code documentation
+=========================
This is a work in progress documentation of the CAcert web application source
code at https://git.cacert.org/gitweb/?p=cacert.git.
@@ -17,6 +17,8 @@ reimplementation.
:maxdepth: 2
:caption: Contents:
+ building
+
Filesystem structure
--------------------