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.
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
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
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.
git clone <repo-name>
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.