From f28cd746c57d9b23f2922ec2b980bdb6c5765a2f Mon Sep 17 00:00:00 2001 From: "Lott, Christopher (cl778h)" Date: Wed, 22 Apr 2020 17:31:33 -0400 Subject: [PATCH] Configure ReadTheDocs build of xapp-frame-cpp Rename and adjust some markup in user-guide.rst to pass Sphinx verify Signed-off-by: Lott, Christopher (cl778h) Change-Id: I24150f0071d4cbdd2ea87f305a752442a984342a --- .gitreview | 14 ++++----- .readthedocs.yaml | 20 ++++++++++++ docs/conf.yaml | 2 +- docs/{user_guide.rst => user-guide.rst} | 56 ++++++++++++++++----------------- tox.ini | 34 ++++++++++++++++++++ 5 files changed, 89 insertions(+), 37 deletions(-) create mode 100644 .readthedocs.yaml rename docs/{user_guide.rst => user-guide.rst} (95%) create mode 100644 tox.ini diff --git a/.gitreview b/.gitreview index 5d8eb80..fc4c1e0 100644 --- a/.gitreview +++ b/.gitreview @@ -1,8 +1,6 @@ - - [gerrit] - host=gerrit.o-ran-sc.org - port=29418 - project=ric-plt/xapp-frame-cpp - defaultbranch=master - asd=asdf - \ No newline at end of file +[gerrit] +host=gerrit.o-ran-sc.org +port=29418 +project=ric-plt/xapp-frame-cpp +defaultbranch=master +defaultremote=origin 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/conf.yaml b/docs/conf.yaml index 85e0266..37fb82e 100644 --- a/docs/conf.yaml +++ b/docs/conf.yaml @@ -1,3 +1,3 @@ --- project_cfg: oran -project: portal-ric-xappframe-cpp +project: ric-plt-xapp-frame-cpp diff --git a/docs/user_guide.rst b/docs/user-guide.rst similarity index 95% rename from docs/user_guide.rst rename to docs/user-guide.rst index 4c5836a..a4ab5e9 100644 --- a/docs/user_guide.rst +++ b/docs/user-guide.rst @@ -48,7 +48,7 @@ the object's constructor with two required parameters: port - A C string (char *) which defines the port that RMR will + A C string (pointer to char) which defines the port that RMR will open to listen for connections. @@ -101,8 +101,8 @@ the object's constructor with two required parameters: will complete and the program will exit as there is no code following the instruction to create the object. - Listening For Messages - ============================================================================================ +Listening For Messages +============================================================================================ The program in the previous example can be extended with just a few lines of code to enable it to receive and process @@ -113,8 +113,8 @@ the object's constructor with two required parameters: registered callback for the message type will be invoked by the framework. - Callback Signature - -------------------------------------------------------------------------------------------- +Callback Signature +-------------------------------------------------------------------------------------------- As with most callback related systems, a callback must have a well known function signature which generally passes event @@ -218,8 +218,8 @@ the object's constructor with two required parameters: it is not necessary to wait for RMR to receive a table from the Route Manager. - Registering A Default Callback - -------------------------------------------------------------------------------------------- +Registering A Default Callback +-------------------------------------------------------------------------------------------- The xApp may also register a default callback function such that the function will be invoked for any message that does @@ -229,8 +229,8 @@ the object's constructor with two required parameters: callback is registered by providing a *generic* message type of xapp->DEFAULT_CALLBACK on an Add_msg_cb call. - The Framework Callback Driver - -------------------------------------------------------------------------------------------- +The Framework Callback Driver +-------------------------------------------------------------------------------------------- The Run() function within the Xapp object is invoked to start the callback driver, and the xApp should not expect the @@ -244,8 +244,8 @@ the object's constructor with two required parameters: callback function will be invoked concurrently from multiple threads. - Sending Messages - ============================================================================================ +Sending Messages +============================================================================================ It is very likely that most xApps will need to send messages and will not operate in "receive only" mode. Sending the @@ -253,7 +253,7 @@ the object's constructor with two required parameters: take one of two forms: - + + $1 Replying to the sender of a received message $1 Sending a message (routed based on the message type and subscription ID) @@ -333,8 +333,8 @@ the object's constructor with two required parameters: based on the mapping of the message type and subscription ID using the current routing table known to RMR. - Direct Payload Manipulation - -------------------------------------------------------------------------------------------- +Direct Payload Manipulation +-------------------------------------------------------------------------------------------- For some applications, it might be more efficient to manipulate the payload portion of an Xapp Message in place, @@ -377,8 +377,8 @@ the object's constructor with two required parameters: Figure 7: Send message without buffer copy. - Sending Multiple Responses - -------------------------------------------------------------------------------------------- +Sending Multiple Responses +-------------------------------------------------------------------------------------------- It is likely that the xApp will wish to send multiple responses back to the process that sent a message that @@ -392,8 +392,8 @@ the object's constructor with two required parameters: necessary, the xApp must make a copy of the payload before the first response call is made. - Message Allocation - -------------------------------------------------------------------------------------------- +Message Allocation +-------------------------------------------------------------------------------------------- Not all xApps will be "responders," meaning that some xApps will need to send one or more messages before they can expect @@ -404,8 +404,8 @@ the object's constructor with two required parameters: can be used to create a Message object with a desired payload size. - Framework Provided Callbacks - ============================================================================================ +Framework Provided Callbacks +============================================================================================ The framework itself may provide message handling via the driver such that the xApp might not need to implement some @@ -418,14 +418,14 @@ the object's constructor with two required parameters: response, all it needs to do is to register its own callback function for the health check message type. - Example Programmes - ============================================================================================ +Example Programmes +============================================================================================ The following sections contain several example programmes which are written on top of the C++ framework. - RMR Dump xAPP - -------------------------------------------------------------------------------------------- +RMR Dump xAPP +-------------------------------------------------------------------------------------------- The RMR dump application is an example built on top of the C++ xApp framework to both illustrate the use of the @@ -649,8 +649,8 @@ the object's constructor with two required parameters: Figure 8: Simple callback application. - Callback Receiver - -------------------------------------------------------------------------------------------- +Callback Receiver +-------------------------------------------------------------------------------------------- This sample programme implements a simple message listener which registers three callback functions to process two @@ -736,8 +736,8 @@ the object's constructor with two required parameters: Figure 9: Simple callback application. - Looping Sender - -------------------------------------------------------------------------------------------- +Looping Sender +-------------------------------------------------------------------------------------------- This is another very simple application which demonstrates how an application can control its own listen loop while diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..00d06df --- /dev/null +++ b/tox.ini @@ -0,0 +1,34 @@ +# This work is licensed under a Creative Commons Attribution 4.0 International License. +# SPDX-License-Identifier: CC-BY-4.0 +# Copyright (C) 2019 AT&T Intellectual Property +# documentation only + +[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 -- 2.16.6