APPC Documentation

Resources for creating ONAP documents

Latest ONAP Documents:

• https://docs.onap.org/

ONAP Documentation Creation:

• http://onap.readthedocs.io/en/latest/guides/onap-developer/how-to-use-docs/index.html

• Readthedocs docs are saved and loaded in rst format.

  • http://docutils.sourceforge.net/rst.html

  • http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Pandoc:

• Used to convert Word documents to rst

• https://pandoc.org

Pandoc – Converting Word Docs to rst

Pandoc installation:

• https://pandoc.org/installing.html

Running pandoc: (note: the embedded image will be created under ./media dir)

Running Pandoc

Testing – Testing rst files using SPHINX

SPHINX (Python Doc Generator)

Sphinx Docs:

• http://www.sphinx-doc.org/en/master

Sphinx and rst:

• http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Install Sphinx:

• http://www.sphinx-doc.org/en/master/usage/installation.html

index.rst

• Must be in the docs root directory

Example index.rst:

conf.py

• Required to test the rst using Sphinx

• Must be copied into the docs root directory after clo0ning from gerrit

• Must be removed from docs root before submitting changes back to gerrit

  • (Won’t necessarily hurt anything but it’s just messy)

Using Sphinx to generate test html

• Once rst updates are made you can generate sample html using sphinx:
  
  
  

• Sample output of html generator:

  
  
  

Resulting html will be displayed:

Open