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 doumentation 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
ONAP is using a set of additional extensions to generate the documentation:
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 are the following:
As a result, we can see on your environment the RST key words 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 extension.
However, it requires some local configuration on your desktop and to set up the following Python libraries:
...