...
RST files are then translated to HTML file using Sphinx Python utility and are then uploaded to the readthedoc web site based on a dedicated Jenkins JobONAP is using a set of additional extensions to generate the documentation:
In a few minutes, your local environment can be setup to help you writing RST files.
We propose 2 configurations:
- A local one: to verify syntax hightligh
- An advanced one: to check loally the generated HTML files as produced by ONAP
Basic Local Envionnement
Many tools are available to write RST files. We propose a solution based on VisualStudioCode that includes a large number of plugins to check that your RST files are correct.
The VisualStudioCode is available here
The useful plugins to add for RST are the following:
As a result, we can see on your environment the RST key words highlighted and some spelling errors as illustrated on the following picture:
Advanced Local Environnement
It is possible to preview the HTML produced by ONAP documentation using the Preview button from the RST extensionbutton 
on the top-right corner.
However, it requires some local configuration on your desktop and
- to set up the following Python libraries.
- to configure the RST plugin
Local Python libraries
ONAP is using a set of Sphinx extensions to generate the documentation:
- sphinxcontrib.blockdiag
- sphinxcontrib.sphinxcontrib-needs
- sphinxcontrib.sphinxcontrib-plantuml
- sphinxcontrib.nwdiag
- sphinxcontrib.seqdiag
- sphinxcontrib.swaggerdoc
- sphinx_rtd_theme
pip install lfdocs-conf
pip install rstcheck
pip install doc8
pip install sphinx sphinx-autobuild
pip install sphinxcontrib.blockdiag
pip install sphinxcontrib.sphinxcontrib-needs
pip install sphinxcontrib.sphinxcontrib-plantuml
pip install sphinxcontrib.nwdiag
pip install sphinxcontrib.seqdiag
pip install sphinxcontrib.swaggerdoc
pip install sphinx_rtd_theme
RST Plugin configuration
In addition, it is important to configure the RST plugin with the following parameter as diplayed in the figure
Click on CTRL and , to display the Settings Panel
Goto 'Extensions' Menu and find 'reStructuredText' line
Conf Path: ${workspaceFolder}/docsDocutils Writer: html
Docutils Writer Part: html_body
Linter: Executable Path: /usr/bin/doc8
Linter: Name: doc8Sphinx Build Path: /usr/local/bin/sphinx-build