Extend class/method docs and publish as user guide
Minor changes to simplify the SDL wrapper methods, none functional.
Bump version to 1.1.2.
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
Change-Id: Ie1d8ace03315bfd9a75aadc933aa66cf3be3e7ff
diff --git a/docs/conf.py b/docs/conf.py
index d695a9a..ccad5c3 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,6 +9,9 @@
# don't alphabetically order
autodoc_member_order = "bysource"
+# Tell numpydoc NOT to generate a list of class members to silence sphinx warnings like this:
+# simple.py:docstring of simple.simple.Simple.rst:20:autosummary: stub file not found 'simple.simple.Simple.hello'. Check your autosummary_generate setting.
+numpydoc_show_class_members = False
linkcheck_ignore = ["http://localhost.*", "http://127.0.0.1.*", "https://gerrit.o-ran-sc.org.*"]
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index 06f01b7..6cfe369 100644
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1,9 +1,13 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T Intellectual Property
Developer Guide
===============
+This document explains how to maintain the RIC Xapp framework.
+Information for users of this framework (i.e., Xapp developers) is in the User Guide.
+
Tech Stack
----------
diff --git a/docs/index.rst b/docs/index.rst
index 09912b9..5004b5b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,6 +12,7 @@
installation-guide.rst
overview.rst
+ user-guide.rst
rmr_api.rst
developer-guide.rst
release-notes.rst
diff --git a/docs/overview.rst b/docs/overview.rst
index d087334..9439bd4 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -5,15 +5,19 @@
Framework Overview
==================
-This package is a framework for writing Xapps in python. The framework
-reduces the amount of code required in an Xapp by providing common
-features needed by all Python-based Xapps including communication with
-the RIC message router (RMR) and the Shared Data Layer (SDL).
+This package is a framework for writing RAN Intelligent Controller
+(RIC) Xapps in python. The framework reduces the amount of code
+required in an Xapp by providing common features needed by all
+Python-based Xapps including communication with the RIC message router
+(RMR) and the Shared Data Layer (SDL).
The framework was designed to suport many types of Xapps, including
-applications that are purely reactive to RMR messages, and
+applications that are purely reactive to RMR messages, and general
applications that initiate actions according to other criteria.
+For complete documentation see the ReadTheDocs site for
+`xapp-frame-py <https://docs.o-ran-sc.org/projects/o-ran-sc-ric-plt-xapp-frame-py>`_.
+
Reactive Xapps
--------------
@@ -23,13 +27,13 @@
This type of application is constructed by creating callback functions
and registering them with the framework by message type. When an RMR
-message arrives, the appropriate callback is invoked. An Xapp may
-define and register a separate callback for each expected message
-type. Every Xapp must define a default callback function, which is
-invoked when a message arrives for which no type-specific callback was
-registered. An analogy of this is AWS Lambda: "execute this code
-every time an event comes in" (the code to execute can depend on the
-type of event).
+message arrives, the appropriate callback is invoked based on the
+message type. An Xapp may define and register a separate callback for
+each expected message type. Every Xapp must define a default callback
+function, which is invoked when a message arrives for which no
+type-specific callback was registered. An analogy of this is AWS
+Lambda: "execute this code every time an event comes in" (the code to
+execute can depend on the type of event).
General Xapps
-------------
@@ -37,14 +41,14 @@
A general Xapp acts according to its own criteria, which may include
receipt of RMR messages.
-This type of application is constructed by creating a function that
-gets invoked by the framework. Typically that function contains a
-`while (something)` event loop. If the function returns, the Xapp
-stops. In this type of Xapp, the Xapp must fetch its own data, either
-from RMR, SDL or other source. The framework does less work for a
-general application compared to a reactive application. The framework
-sets up an RMR thread and an SDL connection, then invokes the
-client-provided function.
+This type of application is constructed by creating a single function
+that is invoked by the framework after initialization. Typically that
+function contains a `while (something)` event loop. When the function
+returns, the Xapp stops. In this usage, the Xapp must fetch its own
+data, either from RMR, SDL or other source. The framework does less
+work for a general application compared to a reactive application; the
+framework only sets up an RMR thread and an SDL connection before
+invoking the client-provided function.
Threading in the Framework
--------------------------
@@ -61,7 +65,7 @@
from the framework-managed queue. The framework is implemented this
way so that a long-running client function (e.g., consume) will not
block RMR reads. This is important because RMR is *not* a persistent
-message bus, if an RMR client does not read fast enough, messages can
+message bus; if an RMR client does not read fast enough, messages can
be lost. So in this framework the client code is not in the same
thread as the RMR reads, to ensure that long-running client code will
not cause message loss.
@@ -80,9 +84,9 @@
reactive Xapps. When an RMR healthcheck message arrives, this handler
checks that the RMR thread is healthy (of course the Xapp cannot even
reply if the thread is not healthy!), and that the SDL connection is
-healthy. The handler responds accordingly via RMA. The Xapp can
+healthy. The handler responds accordingly via RMR. The Xapp can
override this probe handler by registering a new callback for the
-appropriate message type.
+healthcheck message type.
The framework provides no healthcheck handler for general Xapps. Those
applications must handle healthcheck probe messages appropriately when
@@ -96,7 +100,9 @@
--------
Two sample Xapps using this framework are provided in the `examples`
-directory of the git repository. The first, `ping`, is a general Xapp
+directory of the
+`git repository <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/xapp-frame.git;a=tree>`_.
+The first, `ping`, is a general Xapp
that defines a main function that reads its RMR mailbox in addition to
other work. The second, `pong`, is a reactive Xapp that only takes
action when a message is received.
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 74348c9..b58b93a 100644
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -11,6 +11,11 @@
and this project adheres to `Semantic Versioning <http://semver.org/>`__.
+[1.1.2] - 2020-05-13
+--------------------
+* Extend and publish class and method documentation as user guide in RST
+
+
[1.1.1] - 2020-05-07
--------------------
* Use timeout on queue get method to avoid 100% CPU usage (`RIC-354 <https://jira.o-ran-sc.org/browse/RIC-354>`_)
diff --git a/docs/rmr_api.rst b/docs/rmr_api.rst
index a7f0362..69caf59 100644
--- a/docs/rmr_api.rst
+++ b/docs/rmr_api.rst
@@ -1,3 +1,7 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T Intellectual Property
+
RMR Python Bindings
===================
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100644
index 0000000..7147f02
--- /dev/null
+++ b/docs/user-guide.rst
@@ -0,0 +1,40 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T Intellectual Property
+
+User Guide
+==========
+
+This document explains how to develop an Xapp using the RIC Xapp framework.
+Information for maintainers of this framework is in the Developer Guide.
+
+Xapp writers should use the public classes and methods from the Xapp Python
+framework package as documented below.
+
+
+Class RMRXapp
+-------------
+
+Application writers should extend this class to implement a reactive Xapp;
+also see class Xapp.
+
+.. autoclass:: ricxappframe.xapp_frame.RMRXapp
+ :members:
+
+Class Xapp
+----------
+
+Application writers should extend this class to implement a general Xapp;
+also see class RMRXapp.
+
+.. autoclass:: ricxappframe.xapp_frame.Xapp
+ :members:
+
+
+Class SDLWrapper
+----------------
+
+Application writers may instantiate this class directly to communicate with the SDL service.
+
+.. autoclass:: ricxappframe.xapp_sdl.SDLWrapper
+ :members: