Building the documentation

If you are writing new material for the tutorials or the manual, it is helpful to build the documentation pages locally, before submitting the material to the Octopus web server. All that is needed to build the documentation are Hugo and a web server, such as apache

If you already have installed Hugo and started the web server, you can continue with building the pages. Otherwise, follow the instructions to install Hugo and set up a web server.

Installing Hugo

The documentation system requires Hugo at least at version 0.79. Hugo can be downloaded here. For most operating systems, a binary version can be found here.

Once the package is installed, you can check the correct version by

hugo version

sudo apt install ./hugo_0.89.2_Linux-64bit.deb

Installing a web server

The easiest option is to use a docker image for the web server.

Here we assume that you already have docker on your system or know how to install it. In case, you need support, see the official documentation on installing docker

Installing the httpd docker image

Once docker is successfully installed on the system, one can simply pull a pre-defined docker image, which provides the apache2 webserver. For this, use the command:

docker pull httpd

which will download the httpd image.

Starting the docker image:

We assume that $HUGO_DOC is the directory, in which you will clone the documentation repository.

sudo docker run -dit -p 8080:80 -v "$HUGO_DOC/octopus-documentation/public":/usr/local/apache2/htdocs/ httpd

Cloning the repository

The documentation framework is kept in a git repository at gitlab. This repository contains all necessary files (such as the shortcodes, layouts, etc.) and contains the docdock theme as a submodule. Also the octopus code repository is a submodule of the repository. This is required as the source files as well as testfiles will be parsed while building the documentation, and also since from Octopus version 11, all documentation source (i.e. markdown) files will be part of the Octopus source repository.

cd $HUGO_DOC
git clone <repo-name>

cd octopus-documentation
git submodule update --init --recursive

Building the pages

Building the web pages is done by the script

./build-branch -d <Octopus_directory>

which performs the following steps for each selected code version (branch):

• If present, copy <basedir>/doc/html/content/* to $HUGO_DOC/Octopus/content/
• Parse all Octopus source files and build the variables.json file, containing all variable information.
• Parse testsuite input files, as well as tutorial and manual files to create links to variable descriptions.
• Create the variable reference markdown files from thes above information.
• Create class diagrams.
• Run hugo to create the static pages.

If you started the hpptd docker as described above, you can access the pages under http://localhost:8080.