Add documentation in the required format.
Also twiddles the tox to name the code job so that the verify job can be
changed to not run docs.
Issue-ID: RIC-228
Change-Id: I5ded9ae6d421f0906f9fb544ee78dfbf9e8f4291
Signed-off-by: Tommy Carpenter <tc677g@att.com>
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..3797dc8
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,20 @@
+---
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+version: 2
+
+formats:
+ - htmlzip
+
+build:
+ image: latest
+
+python:
+ version: 3.7
+ install:
+ - requirements: docs/requirements-docs.txt
+
+sphinx:
+ configuration: docs/conf.py
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644
index 0000000..c3b6ce5
--- /dev/null
+++ b/docs/_static/logo.png
Binary files differ
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..974c309
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,3 @@
+from docs_conf.conf import *
+
+linkcheck_ignore = ["http://localhost.*", "http://127.0.0.1.*", "https://gerrit.o-ran-sc.org.*"]
diff --git a/docs/conf.yaml b/docs/conf.yaml
new file mode 100644
index 0000000..a98a7eb
--- /dev/null
+++ b/docs/conf.yaml
@@ -0,0 +1,3 @@
+---
+project_cfg: oran
+project: xapp-frame-py
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 0000000..00b0fd0
--- /dev/null
+++ b/docs/favicon.ico
Binary files differ
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..131716b
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,19 @@
+.. 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
+
+
+Welcome to O-RAN SC xapp-frame-py Documentation
+===============================================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ overview.rst
+ release-notes.rst
+ installation-guide.rst
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst
new file mode 100755
index 0000000..ea6090f
--- /dev/null
+++ b/docs/installation-guide.rst
@@ -0,0 +1,16 @@
+.. 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
+
+
+Installation Guide
+==================
+
+.. contents::
+ :depth: 3
+ :local:
+
+Installation
+------------
+
+[SOON THIS WILL BE TRUE] The `ricxappframe` is available in PyPi. Use pip to install the version you want.
diff --git a/docs/logo.png b/docs/logo.png
new file mode 100644
index 0000000..c3b6ce5
--- /dev/null
+++ b/docs/logo.png
Binary files differ
diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644
index 0000000..eca1990
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,50 @@
+.. 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
+
+xapp-frame-py Overview
+======================
+
+This library is a framework for writing Xapps in python.
+There may or may not be many Xapps written in python; however rmr, sdl, and logging libraries all exist for python, and this framework brings them together.
+
+There are (at the time of writing) two "kinds" of Xapps one can instantiate with this framework that model "push" (RMR Xapps) and "pull" (Loop Xapps), as described below.
+
+RMR Xapps
+---------
+This class of Xapps are purely reactive to rmr; data is always "pushed" to it via rmr.
+That is, every time the Xapp receives an rmr message, they do something, then wait for the next message to arrive, end never need to execute functionality at another time (if they do, use the next class).
+This is represented by a very simple callback `consume` that is invoked every time an rmr message arrives (note, this is subject to change, with more callbacks for specific messages like `A1_POLICY_REQUEST`).
+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).
+
+Loop Xapps
+----------
+In this class of Xapp the user simply provides a function that gets invoked, and typically that function has a `while (something)` in it.
+If the function returns, the Xapp will stop.
+In this type of Xapp, the Xapp must "pull" it's own data, typically from SDL, rmr (ie query another component for data), or other sources.
+The framework is "lighter" in this case then the former; it sets up an SDL connection, an rmr thread, and then calls the client provided function.
+This is to be used for Xapps that are not purely event driven.
+
+RMR Threading in the framework
+------------------------------
+NOTE: this is an implementation detail!
+We expose this for transparency but most users will not have to worry about this.
+
+In both types of Xapp, the framework launches a seperate thread whose only job is to read from rmr and deposit all messages (and their summaries) into a thread safe queue.
+When the client Xapp reads using the framework (this read is done by the framework itself in the RMR Xapp, but by the client in a Loop Xapp), the read is done from the queue.
+The framework is implemented this way so that a long running client function (e.g., consume) cannot block rmr reads.
+This is important because rmr is *not* a persistent message bus, if any 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, so that long running client code can never lead to lost messages.
+
+Examples
+--------
+There are two examples in the `examples` directory; `ping` which is a Loop Xapp, and `pong` which is an RMR Xapp. Ping sends a message, pong receives the message and use rts to reply. Ping then reads it's own mailbox and demonstrates other functionality. The highlight to note is that `pong` is purely reactive, it only does anything when a message is received. Ping is a general loop that also happens to read it's rmr mailbox inside.
+
+Current gaps
+------------
+The following are known gaps or potential enhancements at the time of writing.
+::
+
+ * a logger has to be provided to the xapp
+ * the ability to specify more callacks per message type?
+
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
new file mode 100644
index 0000000..37e7c70
--- /dev/null
+++ b/docs/release-notes.rst
@@ -0,0 +1,21 @@
+.. 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
+
+Release Notes
+===============
+
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog <http://keepachangelog.com/>`__
+and this project adheres to `Semantic Versioning <http://semver.org/>`__.
+
+.. contents::
+ :depth: 3
+ :local:
+
+[0.1.0] - 2/27/2020
+-------------------
+::
+
+ * Initial commit
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
new file mode 100644
index 0000000..09a0c1c
--- /dev/null
+++ b/docs/requirements-docs.txt
@@ -0,0 +1,5 @@
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf
diff --git a/tox.ini b/tox.ini
index c7fd69a..43a8d34 100644
--- a/tox.ini
+++ b/tox.ini
@@ -15,11 +15,10 @@
# limitations under the License.
# ==================================================================================
[tox]
-envlist = py37,flake8
-# ,docs,docs-linkcheck
+envlist = code,flake8,docs,docs-linkcheck
minversion = 2.0
-[testenv]
+[testenv:code]
basepython = python3.7
deps=
pytest
@@ -27,7 +26,6 @@
pytest-cov
setenv =
LD_LIBRARY_PATH = /usr/local/lib/:/usr/local/lib64
-
commands =
pytest --junitxml xunit-results.xml --cov ricxappframe --cov-report xml --cov-report term-missing --cov-report html --cov-fail-under=50
coverage xml -i
@@ -41,26 +39,27 @@
[flake8]
extend-ignore = E501,E741,E731
-# verbatim as asked for by the docs instructions: https://wiki.o-ran-sc.org/display/DOC/Configure+Repo+for+Documentation
-# [testenv:docs]
-# basepython = python3.7
-# deps =
-# sphinx
-# sphinx-rtd-theme
-# sphinxcontrib-httpdomain
-# recommonmark
-# lfdocs-conf
+# doc jobs
+[testenv:docs]
+whitelist_externals = echo
+skipsdist = true
+basepython = python3.7
+deps =
+ sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+commands =
+ sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
-#commands =
-# sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
-# echo "Generated docs available in {toxinidir}/docs/_build/html"
-#whitelist_externals = echo
-
-#[testenv:docs-linkcheck]
-#basepython = python3.7
-#deps = sphinx
-# sphinx-rtd-theme
-# sphinxcontrib-httpdomain
-# recommonmark
-# lfdocs-conf
-#commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
+[testenv:docs-linkcheck]
+skipsdist = true
+basepython = python3.7
+deps = sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
