Add documentation for test3, document IPv6 for test
[cacert-infradocs.git] / docs / building.rst
index be32e64..0070aac 100644 (file)
@@ -8,7 +8,8 @@ representations of the documents.
 
 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.
+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`_.
 
@@ -21,24 +22,20 @@ Python 3 installation instructions can be found on the `Python website`_.
    .. code-block:: bash
 
       # Install required operating system packages
-      sudo apt-get install python3 python3-venv make
-      # Setup a fresh virtual Python environment in the venv subdirectory
-      pyvenv venv
-      # Activate the virtual environment
-      . venv/bin/activate
-      # Install the documentation build dependencies (Sphinx, extensions and
-      # their dependencies)
-      pip install -r doc-requirements.txt
-      # Build the documentation in the docs subdirectory
+      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
       cd docs
-      make html
+      pipenv install
+      # Build the documentation in the docs subdirectory
+      pipenv run make html
 
    .. note::
 
       The above commands should be run from the root directory of a git clone
       of the cacert-infradocs git repository. The result of the :program:`make`
-      exection will be available in the :file:`_build/html/` directory inside
-      the :file:`docs/` directory.
+      exection will be available in the :file:`docs/_build/html/` directory.
 
 Getting the documentation source
 --------------------------------
@@ -73,6 +70,9 @@ viewed in the `docs/_build/html directory of the Job's workspace
 <https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/>`_. You may
 open `index.html
 <https://jenkins.cacert.org/job/cacert-infradocs/ws/docs/_build/html/index.html>`_
-to browse the documentation.
+to browse the documentation (there are some JavaScript and SVG glitches due to
+Content-Security-Policy settings).
 
-.. todo:: publish the generated documentation to some canonical place
+If the documentation build is successful the result is pushed to a webserver
+document root on :doc:`systems/webstatic` and is publicly available at
+https://infradocs.cacert.org/.