From: Tommy Carpenter Date: Wed, 6 Nov 2019 12:27:16 +0000 (-0500) Subject: Follow docs instructions. X-Git-Tag: 2.0.0~7 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=4249398baf8e9607f4e2a88d214410affc818666;p=ric-plt%2Fa1.git Follow docs instructions. Change-Id: If54c641be966dc01798a9815d9f82d184ada8452 Signed-off-by: Tommy Carpenter --- diff --git a/.gitignore b/.gitignore index 9180140..5e125ef 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,11 @@ *.log NOTES.txt -docs/* rmr/* +docs_and_diagrams/ + +# documentation +.tox +docs/_build/ .pytest_cache/ xunit-results.xml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 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 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 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..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 --- 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 -========== +---------- - OpenAPI3 - Connexion @@ -27,7 +17,7 @@ Tech Stack - Python3.7 Version bumping -=============== +--------------- 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 -==================== +-------------------- 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 -============ +------------ 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 -=================== +------------------- 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 -=============== +--------------- 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. diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 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 --- 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 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 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 --- 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 `__ and this project adheres to `Semantic Versioning `__. +.. contents:: + :depth: 3 + :local: + + [1.x.x] - TBD :: @@ -110,6 +101,7 @@ and this project adheres to `Semantic Versioning `__. [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 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 8a47c3c..f6d1800 100644 --- a/tox.ini +++ b/tox.ini @@ -15,7 +15,8 @@ # limitations under the License. # ================================================================================== [tox] -envlist = py37,flake8 +envlist = py37,flake8,docs,docs-linkcheck +minversion = 2.0 [testenv] deps= @@ -41,3 +42,27 @@ commands = flake8 setup.py a1 tests [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