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.
The All Scenarios OS documentation is written in reStructuredText markup
.rst file extension) with Sphinx extensions to generate a
structured stand-alone website.
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:
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.
To generate output as HTML, run the following command:
The HTML output is built and can be viewed in your browser from the <docs repository>/build/index.html path.
All the local Sphinx warnings and errors generated during the build process must be fixed and validated.
To validate the changes, execute
make clean && makecommand to generate a clean HTML output.