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.

  1. To check if docker is installed, run: docker --version

  2. 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
    
  3. Restart the terminal.

  4. 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.