Added docs folder

Change-Id: I35f9e646d1d230f6674f6e07d682d75621630cc5
Signed-off-by: wahidw <abdulwahid.w@nokia.com>

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644 (file)
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/container-tag.yaml b/container-tag.yaml
index 18dcc3b..14c7346 100644 (file)
--- a/container-tag.yaml
+++ b/container-tag.yaml
@@ -2,4 +2,4 @@
 # By default this file is in the docker build directory,
 # but the location can configured in the JJB template.
 ---
-tag: 0.3.7
+tag: 0.3.8

diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644 (file)
index 0000000..c3b6ce5
Binary files /dev/null and b/docs/_static/logo.png differ

diff --git a/docs/api-docs.rst b/docs/api-docs.rst
new file mode 100644 (file)
index 0000000..882f99a
--- /dev/null
+++ b/docs/api-docs.rst
@@ -0,0 +1,42 @@
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+
+API-Docs
+========
+
+This is the API-docs of ROUTING MANAGER 
+
+.. contents::
+   :depth: 3
+   :local:
+
+.. note
+
+.. This section is used to describe a software API exposed from a O-RAN software component.  
+   
+.. This note must be removed after content has been added.
+
+
+API Introduction
+-----------------
+.. Please add what API a component have exposed.
+
+API Functions
+-------------
+.. Please states the API functions.
+

diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644 (file)
index 0000000..e59789c
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,30 @@
+#==================================================================================
+#   Copyright (c) 2019 AT&T Intellectual Property.
+#   Copyright (c) 2019 Nokia
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#==================================================================================
+from docs_conf.conf import *
+
+branch = 'latest'
+
+linkcheck_ignore = [
+              'http://localhost',
+                         'http://127.0.0.1.*',
+              'https://gerrit.o-ran-sc.org.*',
+                         'https://github.com.*',
+                         'https://docs.docker.com.*',
+                         'http://rtmgr*'
+]
+#intersphinx_mapping = {}
+#intersphinx_mapping['ric-plt-rtmgr'] = ('https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-ric-plt-rtmgr/en/%s' % branch, None )

diff --git a/docs/conf.yaml b/docs/conf.yaml
new file mode 100644 (file)
index 0000000..349b100
--- /dev/null
+++ b/docs/conf.yaml
@@ -0,0 +1,19 @@
+---
+#==================================================================================
+#   Copyright (c) 2019 AT&T Intellectual Property.
+#   Copyright (c) 2019 Nokia
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#==================================================================================
+project_cfg: oran
+project: ric-plt-rtmgr

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
new file mode 100644 (file)
index 0000000..749b236
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,98 @@
+..
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+Developer-Guide
+===============
+
+.. contents::
+   :depth: 3
+   :local:
+
+Overview
+--------
+Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.
+
+The routing manager has two ways to get the xapp details from xapp manager - httpGetter or httpRESTful.
+In case of httpGetter, the implemented logic periodically queries the xApp Manager component for xApps' list.
+Where in httpRESTful, starts a http server and creates a webhook subscription in xapp manager to update about changes in xapps and waits changed data to arrive on the REST http server.
+Either ways, the xapp data received is stored and then processed to create routing policies and distributes them to all xApps.
+
+Architecture
+------------
+The architecture consists of the following five well defined functions:
+
+* NorthBound Interface (__NBI__): Maintains the communication channels towards RIC manager components
+* Routing Policy Engine (__RPE__): Provides the logic to calculate routing policies
+* Shared Data Layer (__SDL__): Provides access to different kind persistent data stores
+* SouthBound Interface (__SBI__): Maintains the communication channels towards RIC tenants and control components
+* Control Logic (__RTMGR__): Controls the operation of above functions
+
+
+Installing Routing Manager
+--------------------------
+* Tag the `rtmgr` container according to the project release and push it to a registry accessible from all minions of the Kubernetes cluster.
+* Edit the container image section of `rtmgr-dep.yaml` file according to the `rtmgr` image tag.
+
+Deploying Routing Manager
+-------------------------
+* Issue the `kubectl create -f {manifest.yaml}` command in the following order:
+   1. `manifests/namespace.yaml`: creates the `example` namespace for routing-manager resources
+   2. `manifests/rtmgr/rtmgr-cfg.yaml`: creates default routes config file for routing-manager
+   3. `manifests/rtmgr/rtmgr-dep.yaml`: instantiates the `rtmgr` deployment in the `example` namespace
+   4. `manifests/rtmgr/rtmgr-svc.yaml`: creates the `rtmgr` service in `example` namespace
+
+NOTE: The above manifest files will deploy routing manager with NBI as httpRESTful which would not succeed unless there is an xapp manager running at the defined xm-url. The solution is either to deploy a real XAPP manager before deploying routing-manager or start the mock xmgr as mentioned in [Testing](#testing-and-troubleshoting).
+
+Testing and Troubleshooting
+---------------------------
+Testing with Kubernetes
+-----------------------
+Routing Manager's behaviour can be tested using the mocked xApp Manager, traffic generator xApp and receiver xApp.
+
+* Checkout and compile both xApp receiver and xApp Tx generator of RIC admission control project:
+  `https://gerrit.o-ran-sc.org/r/admin/repos/ric-app/admin`
+
+* Copy the `adm-ctrl-xapp` binary to `./test/docker/xapp.build` folder furthermore copy all RMR related dinamycally linked library under `./test/docker/xapp.build/usr` folder. Issue `docker build ./test/docker/xapp.build` command. Tag the recently created docker image and push it to the common registry.
+
+* Copy the `test-tx` binary to `./test/docker/xapp-tx.build` folder furthermore copy all RMR related dinamycally linked library under `./test/docker/xapp.build/usr` folder. Issue `docker build ./test/docker/xapp-tx.build` command.  Tag the recently created docker image and push it to the common registry.
+
+* Enter the `./test/docker/xmgr.build` folder and issue `docker build .`.  Tag the recently created docker image and push it to the common registry.
+
+* Modify the docker image version in each kuberbetes manifest files under `./test/kubernetes/` folder accordingly then issue the `kubectl create -f {manifest.yaml}` on each file.
+
+Once the routing manager is started, it retrievs the initial xapp list from `xmgr` via HTTPGet additonaly it starts to listen on http://rtmgr:8888/v1/handles/xapp-handle endpoint and ready to receive xapp list updates.
+
+* Edit the provided `test/data/xapp.json` file accordingly and issue the following curl command to update `rtmgr's` xapp list.
+
+  `curl --header "Content-Type: application/json" --request POST --data '@./test/data/xapps.json' http://10.244.2.104:8888/v1/handles/xapp-handle`
+
+Executing unit tests
+--------------------
+For running unit tests, execute the following command:
+   `go test ./pkg/nbi` (or any package - feel free to add your own parameters)
+
+If you wish to execute the full UT set with coverage:
+
+   mkdir -p unit-test
+
+   go test ./pkg/sbi ./pkg/rpe ./pkg/nbi ./pkg/sdl -cover -race -coverprofile=$PWD/unit-test/c.out
+
+   go tool cover -html=$PWD/unit-test/c.out -o $PWD/unit-test/coverage.html
+
+
+For troubleshooting purpose the default logging level can be increased to `DEBUG`. (by hand launch it's set to INFO, kubernetes manifest has DEBUG set by default).

diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644 (file)
index 0000000..00b0fd0
Binary files /dev/null and b/docs/favicon.ico differ

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644 (file)
index 0000000..f8ac6da
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,38 @@
+..
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+.. _ric-plt-rtmgr:
+
+Welcome to O-RAN SC Routing Manager
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+   installation-guide.rst
+   developer-guide.rst
+   release-notes.rst
+   api-docs.rst
+
+.. * :doc:`RIC Dashboard <ric-plt-rtmgr:index>`
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst
new file mode 100644 (file)
index 0000000..25ed53f
--- /dev/null
+++ b/docs/installation-guide.rst
@@ -0,0 +1,107 @@
+..
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+
+
+Installation Guide
+==================
+
+.. contents::
+   :depth: 3
+   :local:
+
+Abstract
+--------
+
+This document describes how to install ric-plt/rtmgr, it's dependencies and required system resources.
+
+Introduction
+------------
+Routing Manager is a basic platform service of RIC. It is responsible for distributing routing policies among the other platform components and xApps.
+
+Pre-requisites
+--------------
+* Healthy kubernetes cluster (for Kubernetes testing)
+* Access to the common docker registry (alternatively, you can set up your own private registry for testing: "https://docs.docker.com/registry/deploying/")
+* In case of non-Docker build: 
+    * golang 11.1 at least
+    * go-swagger ("https://github.com/go-swagger/go-swagger", v0.19.0)
+    * glide ("https://github.com/Masterminds/glide")
+    * XApp Manager spec file (available in ORAN: "https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/appmgr" under api folder)
+
+Software Installation and Deployment
+------------------------------------
+This section describes the installation of the ric-plt/rtmgr installation.
+
+Docker Image
+------------
+The Dockerfile located in the project root folder does the following three things:
+
+* As a first step, it creates a build container, fetches XApp Manager's spec file, generates rest api code from swagger spec and builds rtmgr.
+* As a second step, it executes UTs on rtmgr source code.
+* As a third step, it creates the final container from rtmgr binary (Ubuntu based).
+
+For a docker build execute `docker build --tag=rtmgr-build:test .` in the project root directory (feel free to replace the name:tag with your own)
+
+Linux Binary
+------------
+* Compiling without Docker involves some manual steps before compiling directly with "go build".
+* The XApp manager's spec file must be fetched, then api generated with swagger. (these steps are included in the Dockerfile).
+* After the code is generated, glide can install the dependencies of rtmgr.
+* Make sure you set your GOPATH variable correctly (example: $HOME/go/src/routing-manager)
+* Code generation and building example (from project root folder):
+
+  * git clone https://gerrit.o-ran-sc.org/r/ric-plt/appmgr && cp appmgr/api/appmgr_rest_api.yaml api/
+  * swagger generate server -f api/routing_manager.yaml -t pkg/ --exclude-main -r LICENSE
+  * swagger generate client -f api/appmgr_rest_api.yaml -t pkg/ -m appmgr_model -c appmgr_client -r LICENSE
+  * glide install --strip-vendor
+  * go build cmd/rtmgr.go
+
+NOTE: before doing a docker build it is advised to remove any generated files and vendor packages:
+assuming that you stand in project root dir
+
+       rm -rf appmgr vendor pkg/appmgr_* pkg/models pkg/restapi
+
+Command line arguments
+----------------------
+Routing manager binary can be called with `-h` flag when it displays the available command line arguments and it's default value.
+
+Example:
+
+Usage of ./rtmgr:
+   -configfile string
+         Routing manager's configuration file path (default "/etc/rtmgrcfg.json")
+   -filename string
+         Absolute path of file where the route information to be stored (default "/db/rt.json")
+   -loglevel string
+         INFO | WARN | ERROR | DEBUG (default "INFO")
+   -nbi string
+         Northbound interface module to be used. Valid values are: 'httpGetter | httpRESTful' (default "httpGetter")
+   -nbi-if string
+         Base HTTP URL where routing manager will be listening on (default "http://localhost:8888")
+   -rpe string
+         Route Policy Engine to be used. Valid values are: 'rmrpush | rmrpub' (default "rmrpush")
+   -sbi string
+         Southbound interface module to be used. Valid values are: 'nngpush | nngpub' (default "nngpush")
+   -sbi-if string
+         IPv4 address of interface where Southbound socket to be opened (default "0.0.0.0")
+   -sdl string
+         Datastore enginge to be used. Valid values are: 'file' (default "file")
+   -xm-url string
+         HTTP URL where xApp Manager exposes the entire xApp List (default "http://localhost:3000/xapps")
+

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
new file mode 100644 (file)
index 0000000..83bd289
--- /dev/null
+++ b/docs/release-notes.rst
@@ -0,0 +1,69 @@
+..
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+
+Release-Notes
+=============
+
+
+This document provides the release notes for O-RAN SC Amber Release of ric-plt/rtmgr.
+
+.. contents::
+   :depth: 3
+   :local:
+
+Version history
+---------------
+
+Version 1.0.0, November 12, 2019
+--------------------------------
+* Populates the RMR routing table between the RIC platform component pairs E2Term,Subscription Manager and E2Term,E2Manager
+* Queries xAppManager for the deployed xApps and populates the RMR routing table between the xApps,Subscription Manager
+* Populates routes based on the subscription ID between xApps,Subscription Manager
+
+Components
+----------
+* /api: contains Swagger spec files
+* /manifest: contains deployment files (Kubernetes manifests, Helm chart)
+* /cmd: contains go project's main file
+* /pkg: contains go project's internal packages
+* /test: contains CI/CD testing files (scripts, mocks, manifests)
+* Dockerfile: contains main docker file
+* container-tag.yaml: contains CI specific container tag information
+* run_rtmgr.sh: shell script to run rtmgr (requires environment variables to be set)
+
+Current implementation provides support for the followings:
+
+* NBI:
+  * __httpGet__: simple HTTP GET interface. Expects an URL where it gets the xApps' list in JSON format
+  * __httRESTful__: provides REST API endpoints towards RIC manager components. Expects REST port and url where the HTTP service will be started to listen on.
+
+* RPE:
+  * __rmr__: creates routing policies formatted for RIC RMR
+
+* SDL:
+  * __file__: stores xApp data in container's local filesystem (or in a mountpoint)
+  * (backlog) __sdl__: Shared Data Library to Redis database
+
+* SBI:
+  * __nngpub__: distributes RPE created policies via NNG Pub channel
+  * __nngpipe__: distributes RPE created policies via NNG Pipeline channel
+
+
+Limitations
+-----------

diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
new file mode 100644 (file)
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
new file mode 100644 (file)
index 0000000..a2250a7
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,32 @@
+[tox]
+minversion = 2.0
+envlist =
+    docs,
+    docs-linkcheck,
+
+skipsdist = true
+
+[testenv:docs]
+basepython = python3
+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"
+
+whitelist_externals = echo
+
+[testenv:docs-linkcheck]
+basepython = python3
+deps = sphinx
+       sphinx-rtd-theme
+       sphinxcontrib-httpdomain
+       recommonmark
+       lfdocs-conf
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck