ONAP Guidance on Documentation Creating

ONAP has requested to create documentation based on reStructuredText (RST) format to ease the creation and management of the documentations, the guidance can be found at Documentation Creation Guide.

reStructuredText Format

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents.

Detailed information (e.g., specification of the format) can be found at http://docutils.sourceforge.net/rst.html

Doc to Rst Tool

There're several tools available for converting word documents (doc, docx) into rst documents.

The most popular one is Pandoc: https://pandoc.org/, which provides a command line tool for Windows, Linux, MacOS for documentation conversion.

Please follow the install guide to get the tool ready and the manual to use the tool.

The simplest way to use it after installation is to find the document you want to convert in the command line, and execute: pandoc -t rst  SOURCE_FILE.docx -o OUTPUT_FILE.rst

There's also a tutorial video available describing how to install pandoc and use it. 

Testing/Check

There could be some format errors in the converted file which needs manually modification.

You can use an online editor for checking the output of the rst file or finding errors.

• open the website http://rst.ninjs.org/

• type the input in the left column or copy your rst file content into it

• wait a few seconds, and the output would be shown in the right column

• you can check the output (as well as warnings) in the right column