Building All Scenarios OS documentation

This topic outlines the standard way of generating the All Scenarios OS project documentation locally using the source files available in the git.ostc-eu.org repository which aggregates documentation from multiple other components.

Overview

The All Scenarios OS documentation is written in reStructuredText markup language (.rst file extension) with Sphinx extensions to generate a structured stand-alone website.

Prerequisites

To generate the HTML documentation locally, you need to have the following packages pre-installed in your system:

  • Sphinx (for more details on Sphinx installation, check Sphinx Getting Started documentation)

  • The following Sphinx Extensions

    • sphinx-tabs (supports tabbed content in the documentation)

    • sphinxcontrib.plantuml (supports plantuml content)

  • Plantuml (supports UML diagrams)

    The method of installing the plantuml package is dependent on your Linux distribution. For example, on a Ubuntu host, you can install plantuml using the official package repository:

    $ sudo apt-get update -y
    $ sudo apt-get install -y plantuml
    
  • Make (to build the documentation using the provided Makefile)

Building the documentation

To generate a local copy of All Scenarios OS documentation, perform the following steps:

  1. Create a local workspace and clone the All Scenarios OS project files to your local, refer to setting up a repo workspace section for more information.

  2. To generate output as HTML, run the following command:

$ make

The HTML output is built and can be viewed in your browser from the <docs repository>/build/index.html path.

Note

  • All the local Sphinx warnings and errors generated during the build process must be fixed and validated.

  • To validate the changes, execute make clean && make command to generate a clean HTML output.