Building the Documentation

Prerequisites

In order to build and contribute to the documentation you will need the following installed:

• bash
• Docker

Docker is required as all the build steps are performed in docker containers to ensure a consistent and known build environment. It also ensures that the local build environment matches that used in GitHub actions.

It is possible to build the docs without docker but you would need to install all the other dependencies that are provided in the docker images, hugo, npm, etc.

Cloning the event-logging-schema git repository

The git repository for this site is event-logging-schema . event-logging-schema uses the Docsy theme (themes/docsy/) which is pulled in via Go modules. To clone the repository:

# Clone the repo
git clone https://github.com/gchq/event-logging-schema.git
(out)Cloning into 'event-logging-schema'...
(out)remote: Enumerating objects: 66006, done.
(out)remote: Counting objects: 100% (7916/7916), done.
(out)remote: Compressing objects: 100% (1955/1955), done.
(out)remote: Total 66006 (delta 3984), reused 7417 (delta 3603), pack-reused 58090
(out)Receiving objects: 100% (66006/66006), 286.61 MiB | 7.31 MiB/s, done.
(out)Resolving deltas: 100% (34981/34981), done.
cd event-logging-schema

Running a local server

The documentation can be built and served locally while developing it. To build and serve the site run

./container_build/runInHugoDocker.sh server

This uses Hugo to build the site in memory and then serve it from a local web server. When any source files are changed or added Hugo will detect this and rebuild the site as required, including automatically refreshing the browser page to update the rendered view.

Once the server is running the site is available at localhost:1313 .

Building the site locally

To perform a full build of the static site run:

./container_build/runInHugoDocker.sh build

This will generate all the static content and place it in public/.

Generating the PDF

Every page has a Print entire section link that will display a printable view of that section and its children. In addition to this the GitHub Actions we generate a PDF of the docs section and all its children, i.e. all of the documentation (but not News/Releases or Community) in one PDF. This makes the documentation available for offline use.

To test the PDF generation do:

./container_build/runInPupeteerDocker.sh PDF

Updating the Docsy theme

The Docsy theme is pulled in as a Go module. To update the version of Docsy used see Update the Docsy Hugo Module .

When these instructions say to run the hugo command you need to run them using the builder container, unless you have Hugo and Go installed locally. e.g.

./container_build/runInHugoDocker.sh "hugo mod get -u github.com/google/docsy@v0.2.0"