An Example of Creating Documents with ReStructured Text-Sphinx-Readthedocs

Example

We will use a subset of the seed code release notes showing a portion of the top level notes and an example of the details from one component APPC.

Source Files

Top Level Index

.. ONAP documentation master file, created by
   sphinx-quickstart on Mon Jul 10 08:51:21 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to ONAP's documentation!
================================

Contents:

.. toctree::
   :maxdepth: 1

   overview
   install
   tutorial
   release
   usrguide
   devguide

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Sphinx Generated HTML

Release Notes

Release Notes
=============

Summary
-------
OpenECOMP 1.0.0 represents a complete demo platform with two
service examples as contributed by AT&T to the Linux Foundation ONAP project.

Installation Instructions
-------------------------

BasicOpenECOMP installation instructions are available as a `README.md
 <https://nexus.openecomp.org/content/sites/raw/org.openecomp.demo/heat/1.0.0-SNAPSHOT/README.md>`_  file. 
Step by step tutorials for setting up a Rackspace account, using the portal,
 designing services, and instantiating services are provided here.


Components
----------

.. toctree::
   :maxdepth: 1

   r/appc/doc/relnotes

The r/... reference is based on git submodule references in the /doc repository to other project repos, this may change as we create the ONAP structure

APPC Release Notes

APPC
====

Delivery
--------

The APPC package is composed of three Docker images hosted on a single Ubuntu 14.04 LTS VM instance (medium flavor (Memory 4 Gb, 4 vCPU, 80 Gb Disk)

Docker Diagram
--------------

.. image:: appc-containers.png

APIs
----

.. csv-table:: Offered
 :header: "Container/VM Name", "API Name", "API Purpose", "Protocol Used", Port number or range used", "TCP/UDP"
 :widths: 20, 50, 20, 10, 10, 10

 "APPC", "<http-protocol>://<appc-ip>:<appc-api-port>/restconf/operations/appc-provider-lcm:<command-name> (ex: https://<appc-ip>:8443/restconf/operations/appc-provider:modifiy-config)", "Offer APPC APIs", "https", "8181", "TCP"
 "APPC", "DMaap Adapter", "Interface to DMaap", "https", "3904", "TCP"
 "DB", "MySQL", "Access to MySQL DB", "", "3306", "TCP"

.. csv-table:: Consumed
 :header: "Container/VM Name", "API Name", "API Purpose", "Protocol Used", Port number or range used", "TCP/UDP"
 :widths: 20, 50, 20, 10, 10, 10

 "APPC", "<http-protocol>://<appc-ip>:<appc-api-port>/restconf/operations/appc-provider-lcm:<command-name> (ex: https://<appc-ip>:8443/restconf/operations/appc-provider:modifiy-config)", "Offer APPC APIs", "https", "8181", "TCP"
 "APPC", "DMaap Adapter", "Interface to DMaap", "https", "3904", "TCP"

Logging/Diagnostic Information
------------------------------

There are three places where we can look for diagnostics/logging information based on the situation at hand:

* **Cloud-Init Console Log:** This log shows the output results of the cloud-init script that is deploying the APP-C VM. The log can be found on the Rackspace/OpenStack Dashboard where you are deploying your VM from, in the deployed VM itself (usually found in /var/log/cloud-init.log), or by calling the OpenStack API to output the cloud-init log (by obtaining information from the metadata server of your cloud platform).


* **Karaf Log:** This log shows the output results of the APP-C/SDN-C Karaf features & bundles installed in the OpenDaylight framework. You can look here to troubleshoot any Karaf features and/or bundles that failed to install properly. The log can be found inside the APP-C Docker Container in the /opt/opendaylight/current/log

 * NOTE: Some errors will not show in detail unless the verbose option is enabled for karaf. To do this, log in to the Karaf client (explained in the APP-C documentation) and type in "log:set DEBUG" to enable verbose logging, and "log:set INFO" to disable verbose logging.

* **Docker-Compose Logs:** This log is the output from when you trigger the docker-compose process to start (which starts thedocker containers). It can be found in two ways:

 * If running docker-compose right off the shell session ("docker-compose up"), the output will be displayed there.

 * If running docker-compose as a daemon/background process (RECOMMENDED - "docker-compose up -d"), you can open any other shell session and run "docker-compose logs -f" to obtain live logs from the docker-compose containers' instantiations.

Guide for Users

We can reuse most of this OPNFV Guide with minor modifications to reflect

ONAP project name
Different document structure and templates that apply to ONAP
Gerrit repo structure that has more levels of hierarchy

Templates

These OPNFV Templates may be useful as starting point on how to organize templates and / or some maybe applicable with minor modification to ONAP.

Integration with CI/CD

This approach aligns with the CI/CD infrastructure and developer workflows including

Document source from other projects is maintained in same repository as source code
Rebuild of documentation is triggered by changes in any of the source
Verification of documentation prior to creating a new version at Readthedocs

The OPNFV Doc Jenkins Verify and Merge Jobs illustrates the integration with tox/Sphinx to verify documents and to trigger publishing a new version at Readthedocs.