Building Oniro Project Documentation

This topic outlines the standard way of generating the Oniro Project project documentation locally using the source files available in the gitlab.eclipse.org repository which aggregates documentation from multiple other components.

Overview

The Oniro Project 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 Oniro Project documentation, perform the following steps:

  1. Create a local workspace and clone the Oniro Project 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.

Reference

https://www.sphinx-doc.org/en/master/contents.html

https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html