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:

  Running Sphinx v1.5.3 /usr/local/lib/python2.7/dist-packages/sphinx/util/requests.py:58: UserWarning: Some links may return broken results due to being unable to check the Server Name Indication (SNI) in the returned SSL cert against the hostname in the url requested. Recommended to install requests-2.4.1+. 'Some links may return broken results due to being unable to ' loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 0 added, 1 changed, 0 removed reading sources... [100%] APPC CDT Guide/APPC CDT Guide looking for now-outdated files... none found pickling environment... done checking consistency... /home/scottseabolt/appc/docs/release-notes.rst:: WARNING: document isn't included in any toctree done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying images... [100%] APPC CDT Guide/media/image34.png copying downloadable files... [100%] APPC CDT Guide/Generic 1802 User Input Spreadsheet v.02.xlsx copying static files... WARNING: html_static_path entry u'/home/scottseabolt/appc/docs/_static' does not exist WARNING: logo file '_static/logo_onap_2017.png' does not exist WARNING: favicon file '_static/favicon.ico' does not exist done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded, 4 warnings.

  
  
  

Resulting html will be displayed:

Open