*.log
NOTES.txt
-docs/*
rmr/*
+docs_and_diagrams/
+
+# documentation
+.tox
+docs/_build/
.pytest_cache/
xunit-results.xml
--- /dev/null
+---
+version: 2
+
+formats:
+ - htmlzip
+
+build:
+ image: latest
+
+python:
+ version: 3.7
+ install:
+ - requirements: docs/requirements-docs.txt
+
+sphinx:
+ configuration: docs/conf.py
--- /dev/null
+from docs_conf.conf import *
+
+linkcheck_ignore = ["http://localhost.*", "http://127.0.0.1.*", "https://gerrit.o-ran-sc.org.*"]
--- /dev/null
+---
+project_cfg: oran
+project: a1
-.. ==================================================================================
-.. 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
- Python3.7
Version bumping
-===============
+---------------
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``
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``.
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
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``
::
- 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.
-.. ==================================================================================
-.. 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`
--- /dev/null
+.. 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
+
--- /dev/null
+.. 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/``.
-.. ==================================================================================
-.. 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/>`__.
+.. contents::
+ :depth: 3
+ :local:
+
+
[1.x.x] - TBD
::
[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
--- /dev/null
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf
# limitations under the License.
# ==================================================================================
[tox]
-envlist = py37,flake8
+envlist = py37,flake8,docs,docs-linkcheck
+minversion = 2.0
[testenv]
deps=
[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
Code Review / ric-plt / a1.git / commitdiff
