Follow docs instructions.

Change-Id: If54c641be966dc01798a9815d9f82d184ada8452
Signed-off-by: Tommy Carpenter <tc677g@att.com>

diff --git a/.gitignore b/.gitignore
index 9180140..5e125ef 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,11 @@
 *.log
 NOTES.txt
 *.log
 NOTES.txt

-docs/*

 rmr/*
 rmr/*

+docs_and_diagrams/
+
+# documentation
+.tox
+docs/_build/

 
 .pytest_cache/
 xunit-results.xml
 
 .pytest_cache/
 xunit-results.xml

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644 (file)
index 0000000..095222a
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,16 @@
+---
+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 (file)
index 0000000..c3b6ce5
Binary files /dev/null and b/docs/_static/logo.png differ

diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644 (file)
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 (file)
index 0000000..8f8b08a
--- /dev/null
+++ b/docs/conf.yaml
@@ -0,0 +1,3 @@
+---
+project_cfg: oran
+project: a1

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index ca92214..38722da 100644 (file)
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1,25 +1,15 @@
-.. ==================================================================================
-..       Copyright (c) 2019 Nokia
-..       Copyright (c) 2018-2019 AT&T Intellectual Property.
-..
-..   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.
-.. ==================================================================================
-
-A1 Dev Guide
-============
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Developer-Guide
+===============
+
+.. contents::
+   :depth: 3
+   :local:

 
 Tech Stack
 
 Tech Stack

-==========
+----------

 
 -  OpenAPI3
 -  Connexion
 
 -  OpenAPI3
 -  Connexion


@@ -27,7 +17,7 @@ Tech Stack
 -  Python3.7
 
 Version bumping
 -  Python3.7
 
 Version bumping

-===============
+---------------

 
 This project follows semver. When changes are made, the versions are in:
 
 
 This project follows semver. When changes are made, the versions are in:
 


@@ -45,7 +35,7 @@ This project follows semver. When changes are made, the versions are in:
 
 
 Version bumping rmr
 
 
 Version bumping rmr

-====================
+--------------------

 rmr is a critical dependency of A1. Bumping the rmr version dependency requires changes in:
 
 1) ``Dockerfile``
 rmr is a critical dependency of A1. Bumping the rmr version dependency requires changes in:
 
 1) ``Dockerfile``


@@ -65,7 +55,7 @@ Run the integration tests after attempting this.
 
 
 Unit Testing
 
 
 Unit Testing

-============
+------------

 Note,  before this will work, for the first time on the machine running the tests, run ``./install_deps.sh``. This is only needed once on the machine.
 Also, this requires the python packages ``tox`` and ``pytest``.
 
 Note,  before this will work, for the first time on the machine running the tests, run ``./install_deps.sh``. This is only needed once on the machine.
 Also, this requires the python packages ``tox`` and ``pytest``.
 


@@ -81,7 +71,7 @@ Alternatively, you can run the unit tests in Docker (this is somewhat less nice
    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
 
 Integration testing
    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
 
 Integration testing

-===================
+-------------------

 This tests A1’s external API with two test receivers. This depends on helm+k8s, meaning you cannot run this if this is not installed.
 
 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything
 This tests A1’s external API with two test receivers. This depends on helm+k8s, meaning you cannot run this if this is not installed.
 
 Unlike the unit tests, however, this does not require rmr to be installed on the base system, as everything


@@ -116,7 +106,7 @@ Unless you're a core A1 developer, you should probably stop here. The below inst
 are for running A1 locally, without docker, and is much more involved (however useful when developing a1).
 
 Running locally
 are for running A1 locally, without docker, and is much more involved (however useful when developing a1).
 
 Running locally

-===============
+---------------

 
 1. Before this will work, for the first time on that machine, run ``./install_deps.sh``
 
 
 1. Before this will work, for the first time on that machine, run ``./install_deps.sh``
 


@@ -139,9 +129,9 @@ Running locally
 
    ::
 
 
    ::
 

-   sudo pip install -e .
-   set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
-   /usr/bin/run.py
+     sudo pip install -e .
+     set -x LD_LIBRARY_PATH /usr/local/lib/; set -x RMR_SEED_RT /opt/route/local.rt ; set -x RMR_RCV_RETRY_INTERVAL 500; set -x RMR_RETRY_TIMES 10;
+     /usr/bin/run.py

 
 
 There are also two test receivers in ``integration_tests`` you can run locally.
 
 
 There are also two test receivers in ``integration_tests`` you can run locally.

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
index 7cb73bf..026c940 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,60 +1,21 @@
-.. ==================================================================================
-..       Copyright (c) 2019 Nokia
-..       Copyright (c) 2018-2019 AT&T Intellectual Property.
-..
-..   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.
-.. ==================================================================================
-
-A1 Mediator
-===========
-
-API
-===
-
-You can see the API (OpenAPI3 spec) at ``a1/openapi.yml``. You can also
-see the “pretty” version if you run the container at
-``http://localhost:10000/ui/``.
-
-Running
-=======
-
-Optional ENV Variables
-----------------------
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0

 
 

-You can set the following ENVs to change the A1 behavior:
+Welcome to O-RAN SC A1 Documentation
+=====================================

 
 

-1. ``RMR_RETRY_TIMES`` the number of times failed rmr operations such as
-timeouts and send failures should be retried before A1 gives up and
-returns a 503. The default is ``4``.
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

 
 

-K8S
----
-The "real" helm chart for A1 is in the LF it/dep repo. That repo holds all of the helm charts for the RIC platform. There is a helm chart in `integration_tests` here for running the integration tests as discussed above.
-
-Local Docker
-------------
-
-building
-~~~~~~~~
-::
-
-   docker build --no-cache -t a1:X.Y.Z .
-
-.. _running-1:
-
-running
-~~~~~~~
-
-::
+   overview.rst
+   developer-guide.rst
+   release-notes.rst
+   installation-guide.rst
+..
+   user-guide.rst
+   api-docs.rst

 
 

-   docker run -dt -p 10000:10000 -v /path/to/localrt:/opt/route/local.rt -v /path/to/ricmanifest:/opt/ricmanifest.json a1:X.Y.Z -v
+* :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..5ddad48
--- /dev/null
+++ b/docs/installation-guide.rst
@@ -0,0 +1,41 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+Installation Guide
+==================
+
+.. contents::
+   :depth: 3
+   :local:
+
+Optional ENV Variables
+----------------------
+
+You can set the following ENVs to change the A1 behavior:
+
+1. ``RMR_RETRY_TIMES`` the number of times failed rmr operations such as
+timeouts and send failures should be retried before A1 gives up and
+returns a 503. The default is ``4``.
+
+K8S
+---
+The "real" helm chart for A1 is in the LF it/dep repo. That repo holds all of the helm charts for the RIC platform. There is a helm chart in `integration_tests` here for running the integration tests as discussed above.
+
+Local Docker
+-------------
+
+building
+~~~~~~~~
+::
+
+   docker build --no-cache -t a1:X.Y.Z .
+
+.. _running-1:
+
+running
+~~~~~~~
+
+::
+
+   docker run -dt -p 10000:10000 -v /path/to/localrt:/opt/route/local.rt -v /path/to/ricmanifest:/opt/ricmanifest.json a1:X.Y.Z -v
+

diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644 (file)
index 0000000..45d98ba
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+
+A1 Mediator
+===========
+
+API
+---
+
+You can see the API (OpenAPI3 spec) at ``a1/openapi.yml``. You can also
+see the “pretty” version if you run the container at
+``http://localhost:10000/ui/``.

diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index 5173a25..4049f40 100644 (file)
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -1,28 +1,19 @@
-.. ==================================================================================
-..       Copyright (c) 2019 Nokia
-..       Copyright (c) 2018-2019 AT&T Intellectual Property.
-..
-..   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.
-.. ==================================================================================
-
-A1 Mediator Release Notes
-=========================
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+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/>`__.
 
 
 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:
+
+

 [1.x.x] - TBD
 
 ::
 [1.x.x] - TBD
 
 ::


@@ -110,6 +101,7 @@ and this project adheres to `Semantic Versioning <http://semver.org/>`__.
 
 [0.12.1] - 9/20/2019
 ::
 
 [0.12.1] - 9/20/2019
 ::

+

     * switch to rmr 1.8.1 to pick up a non blocking variant of rmr that deals with bad routing tables (no hanging connections / blocking calls)
     * improve test receiver to behave with this setup
     * add integration test for this case
     * switch to rmr 1.8.1 to pick up a non blocking variant of rmr that deals with bad routing tables (no hanging connections / blocking calls)
     * improve test receiver to behave with this setup
     * add integration test for this case

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
index 8a47c3c..f6d1800 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -15,7 +15,8 @@
 #   limitations under the License.
 # ==================================================================================
 [tox]
 #   limitations under the License.
 # ==================================================================================
 [tox]

-envlist = py37,flake8
+envlist = py37,flake8,docs,docs-linkcheck
+minversion = 2.0

 
 [testenv]
 deps=
 
 [testenv]
 deps=


@@ -41,3 +42,27 @@ commands = flake8 setup.py a1 tests
 
 [flake8]
 extend-ignore = E501,E741
 
 [flake8]
 extend-ignore = E501,E741

+
+# 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
+
+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