NOW AVAILABLE: Setup of a Documentation Development System
This guide provides a detailed description to set up a system suitable to create, check and preview documentation locally. The targeted readership are beginners and people interested in creating documentation. The guide describes the setup of a development system from scratch using the Ubuntu Desktop version installed in a virtual machine. It includes all required steps and also some optional ones that may ease your daily work with this development system.
Read more here: https://docs.onap.org/en/latest/guides/onap-documentation/setup-of-a-doc-dev-system.html
Context
ONAP documentation is using reStructuredText (RST) as input format.
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 Job
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 highlight
- An advanced one: to check locally the generated HTML files as produced by ONAP
Basic Local Environnement
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 extension 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 Environment
It is possible to preview the HTML produced by ONAP documentation using the Preview button 
on the top-right corner.
However, it requires some local configuration on your desktop
- to set up the following Python libraries.
- to configure the RST plugin
Local Python libraries
You must use Python3 version.
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 with version <0.6.0
- sphinxcontrib.redoc
- sphinx_rtd_theme
Make sure you are in a Python 3 environment.
Install needed packages:...
RST Plugin configuration
In addition, it is important to configure the RST plugin with the following parameter as displayed in the figure
...
Conf Path: ${workspaceFolder}/docs
Docutils Writer: html
Docutils Writer Part: html_body
Linter: Executable Path: /usr/bin/doc8 or $VIRTUAL_ENV/bin/doc8 if you are in a python 3 virtual env (and launched Visual studio code from it)
Linter: Name: doc8
Sphinx Build Path: /usr/local/bin/sphinx-build or $VIRTUAL_ENV/bin/sphinx-build if you are in a python 3 virtual env (and launched Visual studio code from it)
Note: you an also use the settings.json file under <home>.config/Code/User and add the following properties
{
"restructuredtext.confPath": "${workspaceFolder}/docs",
"restructuredtext.sphinxBuildPath": "/usr/local/bin/sphinx-build",
"restructuredtext.linter.executablePath": "/usr/bin/doc8",
"restructuredtext.linter.name": "doc8"
}
...