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 images/media dir)

pandoc --extract-media=images -s mydoc.docx -t rst -o mydoc.rst

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

.. This work is licensed under a Creative
Commons Attribution 4.0 International License.

APPC Documentation Repository
-----------------------------
.. toctree::
:maxdepth: 2
  
	APPC LCM API Guide/APPC LCM API Guide
	APPC Client Library Guide/APPC Client Library Guide  
	APPC Logging Guide/APPC Logging Guide
	APPC User Guide/APPC User Guide  
	APPC OAM API Guide/APPC OAM API Guide 
	APPC CDT Guide/APPC CDT Guide

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:
  
  

sphinx-build -b html /home/myhome/appc/docs /home/myhome/test

• 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: