Building the RiskScape documentation

Prerequisites

Warning

In order to build the documentation locally, you will need Docker installed.

Installing Docker

Note

The instructions here are for installing Docker on Linux Ubuntu.

To check if docker is installed, run: docker --version
Install docker if it is not there. Refer to the Docker documentation for more details, or try running the following command for Ubuntu users:
```
sudo apt-get install docker-ce docker-ce-cli containerd.io
```
Restart the terminal.
Run: docker --version or docker ps (for permission)

Tip

You will want to be able to run Docker as a non-root user. Follow the instructions here to set that up.

Documentation

The RiskScape documentation is built using Sphinx and is written in Markdown and reStructuredText.

There are scripts that will build the documentation using a Docker container, which ensures they are built the same way each time.

The documentation is located in the RiskScape source tree under the ./docs directory. In that directory there is:

source - this is where the source files for the documentation are. These are the markdown files that can be edited.
build - this folder will not exist until the docs have been built. The build creates HTML files using the Markdown files as the source.

Style guide

Documentation should be written to conform with the documentation style guide. Refer to ./docs/README.md for more details.

Building the documentation

To build the docs run this command:

./bin/build-docs.sh

This will run the docker container with your source code and build the HTML files for the documents. Once built open the index file at docs/build/html/index.html, e.g.

firefox docs/build/html/index.html

Once you have proofread and confirmed your changes are complete, refer to the Contributing to RiskScape workflow.