Rename and adjust some markup in user-guide.rst to pass Sphinx verify
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
Change-Id: I24150f0071d4cbdd2ea87f305a752442a984342a
-
- [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
--- /dev/null
+---
+# .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
-project: portal-ric-xappframe-cpp
+project: ric-plt-xapp-frame-cpp
- 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.
open to listen for connections.
will complete and the program will exit as there is no code
following the instruction to create the object.
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
The program in the previous example can be extended with just
a few lines of code to enable it to receive and process
registered callback for the message type will be invoked by
the framework.
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
As with most callback related systems, a callback must have a
well known function signature which generally passes event
it is not necessary to wait for RMR to receive a table from
the Route Manager.
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
The xApp may also register a default callback function such
that the function will be invoked for any message that does
callback is registered by providing a *generic* message type
of xapp->DEFAULT_CALLBACK on an Add_msg_cb call.
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
The Run() function within the Xapp object is invoked to start
the callback driver, and the xApp should not expect the
callback function will be invoked concurrently from multiple
threads.
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
It is very likely that most xApps will need to send messages
and will not operate in "receive only" mode. Sending the
$1 Replying to the sender of a received message
$1 Sending a message (routed based on the message type and subscription ID)
$1 Replying to the sender of a received message
$1 Sending a message (routed based on the message type and subscription ID)
based on the mapping of the message type and subscription ID
using the current routing table known to RMR.
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,
For some applications, it might be more efficient to
manipulate the payload portion of an Xapp Message in place,
Figure 7: Send message without buffer copy.
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
It is likely that the xApp will wish to send multiple
responses back to the process that sent a message that
necessary, the xApp must make a copy of the payload before
the first response call is made.
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
Not all xApps will be "responders," meaning that some xApps
will need to send one or more messages before they can expect
can be used to create a Message object with a desired payload
size.
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
The framework itself may provide message handling via the
driver such that the xApp might not need to implement some
response, all it needs to do is to register its own callback
function for the health check message type.
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.
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
The RMR dump application is an example built on top of the
C++ xApp framework to both illustrate the use of the
Figure 8: Simple callback application.
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
This sample programme implements a simple message listener
which registers three callback functions to process two
Figure 9: Simple callback application.
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
This is another very simple application which demonstrates
how an application can control its own listen loop while
--- /dev/null
+# 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