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
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
- 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.