You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

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 highligh
  • 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 plugins 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

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

Make sure you are in a Python 3 environment:

python3 -m venv Python3 
source Python3/bin/activate

Install needed packages:

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 displayed in the figure


Click on  CTRL and , to display the Settings Panel
Goto 'Extensions' Menu and find 'reStructuredText' line




 


Conf Path: ${workspaceFolder}/docs
Docutils Writer: html
Docutils Writer Part: html_body
Linter:  Executable Path: /usr/bin/doc8
Linter: Name: doc8Sphinx Build Path: /usr/local/bin/sphinx-build


Note: you need to open a Folder associated with the ONAP component


  • No labels