Add generated API doc to RST
The ReadTheDocs builder will never have RMR library installed,
so it's nearly impossible to use the sphinx autodoc API generator
to extract Pydoc strings from the code. This hack adds the
generated strings to a static file which will require manual
maintenance, poor but an improvement on zero documentation.
Issue-ID: RIC-228
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>
Change-Id: Icf3121c960424eb5f83eac76dbcae55d2f64624b
diff --git a/docs/index.rst b/docs/index.rst
index 6ba4452..41d6630 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,17 +3,17 @@
.. Copyright (C) 2020 AT&T Intellectual Property
-Welcome to O-RAN SC xapp-frame-py Documentation
-===============================================
+xApp Python Framework
+=====================
.. toctree::
:maxdepth: 2
:caption: Contents:
- overview.rst
- release-notes.rst
installation-guide.rst
+ overview.rst
rmr_api.rst
+ release-notes.rst
* :ref:`genindex`
* :ref:`modindex`
diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst
index c3254f3..0785c40 100755
--- a/docs/installation-guide.rst
+++ b/docs/installation-guide.rst
@@ -10,12 +10,16 @@
:depth: 3
:local:
-Installation
-------------
+The `ricxappframe` is available in `PyPi <https://pypi.org/project/ricxappframe>`_ .
+Use pip to install the version you want.
-The `ricxappframe` is available in `PyPi <https://pypi.org/project/ricxappframe>`_ . Use pip to install the version you want.
-
-Installing the ricxappframe does NOT install the underlying rmr system dependency.
-The underlying dependencies are in C.
-For information on how to install rmr itself, see here for `packages <https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=3605041>`_ and here to install from `source <https://wiki.o-ran-sc.org/display/RICP/RMR+Building+From+Source>`_.
-Alternatively, you can borrow a script (note, this file contains an rmr version that is subject to change!) in the `a1 <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/a1.git;a=blob;f=integration_tests/install_rmr.sh;h=70ee489ba2895ea67ca2c93ecefb2776ba2c9ff3;hb=78ba273b279a7e7af6dba811a29746b881a53a8e>`_ repo.
+Installing the ricxappframe package does NOT install the required RMR system library,
+a shared object written in C and available for most Linux systems.
+For information on how to install the RMR system library, see here for
+`DEB/RPM packages <https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=3605041>`_
+and here to install from
+`source <https://wiki.o-ran-sc.org/display/RICP/RMR+Building+From+Source>`_.
+Alternatively, you can use a script (note, this file contains an RMR version
+that is subject to change!) in the
+`a1 <https://gerrit.o-ran-sc.org/r/gitweb?p=ric-plt/a1.git;a=blob;f=integration_tests/install_rmr.sh;h=70ee489ba2895ea67ca2c93ecefb2776ba2c9ff3;hb=78ba273b279a7e7af6dba811a29746b881a53a8e>`_
+repo.
diff --git a/docs/overview.rst b/docs/overview.rst
index a572390..ffac38f 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -2,8 +2,8 @@
.. SPDX-License-Identifier: CC-BY-4.0
.. Copyright (C) 2020 AT&T Intellectual Property
-xapp-frame-py Overview
-======================
+Framework Overview
+==================
This library is a framework for writing Xapps in python.
There may or may not be many Xapps written in python; however rmr, sdl, and logging libraries all exist for python, and this framework brings them together.
diff --git a/docs/rmr_api.rst b/docs/rmr_api.rst
index e3d5f0e..d1f6d98 100644
--- a/docs/rmr_api.rst
+++ b/docs/rmr_api.rst
@@ -1,16 +1,746 @@
-RMR
-====
+RMR Python Bindings
+===================
Overview
--------
-The xapp framework repo includes a python submodule called `rmr`.
-This package (`ricxappframe.rmr`) is a CTYPES wrapper around the C rmr library.
-Most Xapp users will never use this package natively; however python apps that need access to the low level rmr API can use this package.
-Usage of this python package requires that you have the c rmr libraries installed.
+
+The xapp python framework repository includes a python submodule
+called `rmr`. This package (`ricxappframe.rmr`) is a CTYPES wrapper
+around the RMR shared library. Most Xapp users will never use this
+package natively; however python apps that need access to the low
+level RMR API can use this package. Usage of this python package
+requires that you have the RMR shared-object library installed.
-.. API
-.. ---
+RMR API
+-------
-.. .. automodule:: ricxappframe.rmr.rmr
-.. :members:
+..
+ Sphinx can generate API documentation by running Python to pull doc strings
+ from the binding code using these Sphinx directives that are commented out:
+ .. automodule:: ricxappframe.rmr.rmr
+ :members:
+ But that approach requires the RMR library to be installed, which is difficult
+ to achieve at ReadTheDocs.io. Instead, the RST below was generated and captured
+ according to the method shown at
+ https://stackoverflow.com/questions/2668187/make-sphinx-generate-rst-class-documentation-from-pydoc
+
+
+
+.. py:module:: ricxappframe.rmr.rmr
+
+
+..
+ !! processed by numpydoc !!
+
+.. py:class:: rmr_mbuf_t
+ :module: ricxappframe.rmr.rmr
+
+
+ Reimplementation of rmr_mbuf_t which is in an unaccessible header file (src/common/include/rmr.h)
+
+ | typedef struct {
+ | int state; // state of processing
+ | int mtype; // message type
+ | int len; // length of data in the payload (send or received)
+ | unsigned char* payload; // transported data
+ | unsigned char* xaction; // pointer to fixed length transaction id bytes
+ | int sub_id; // subscription id
+ | int tp_state; // transport state (a.k.a errno)
+ |
+ | these things are off limits to the user application
+ |
+ | void* tp_buf; // underlying transport allocated pointer (e.g. nng message)
+ | void* header; // internal message header (whole buffer: header+payload)
+ | unsigned char* id; // if we need an ID in the message separate from the xaction id
+ | int flags; // various MFL (private) flags as needed
+ | int alloc_len; // the length of the allocated space (hdr+payload)
+ | } rmr_mbuf_t;
+
+ We do not include the fields we are not supposed to mess with
+
+ RE PAYLOADs type below, see the documentation for c_char_p:
+ class ctypes.c_char_p
+ Represents the C char * datatype when it points to a zero-terminated string. For a general character pointer that may also point to binary data, POINTER(c_char) must be used. The constructor accepts an integer address, or a bytes object.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ :Attributes:
+
+ **len**
+ Structure/Union member
+
+ **mtype**
+ Structure/Union member
+
+ **payload**
+ Structure/Union member
+
+ **state**
+ Structure/Union member
+
+ **sub_id**
+ Structure/Union member
+
+ **tp_state**
+ Structure/Union member
+
+ **xaction**
+ Structure/Union member
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_init(uproto_port, max_msg_size, flags)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to rmr C documentation for rmr_init
+ extern void* rmr_init(char* uproto_port, int max_msg_size, int flags)
+
+ This python function checks that the context is not None and raises
+ an excption if it is.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_ready(vctx)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to rmr C documentation for rmr_ready
+ extern int rmr_ready(void* vctx)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_close(vctx)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to rmr C documentation for rmr_close
+ extern void rmr_close(void* vctx)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_set_stimeout(vctx, time)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_set_stimeout
+ extern int rmr_set_stimeout(void* vctx, int time)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_alloc_msg(vctx, size, payload=None, gen_transaction_id=False, mtype=None, meid=None, sub_id=None, fixed_transaction_id=None)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_alloc_msg
+ extern rmr_mbuf_t* rmr_alloc_msg(void* vctx, int size)
+ TODO: on next API break, clean up transaction_id ugliness. Kept for now to preserve API.
+
+ if payload is not None, attempts to set the payload
+ if gen_transaction_id is True, it generates and sets a transaction id. Note, fixed_transaction_id supersedes this option
+ if mtype is not None, sets the sbuf's message type
+ if meid is not None, sets the sbuf's meid
+ if sub_id is not None, sets the sbud's subscription id
+ if fixed_transaction_id is set, it deterministically sets the transaction_id. This overrides the option gen_transation_id
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_realloc_payload(ptr_mbuf, new_len, copy=False, clone=False)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_realloc_payload().
+ extern rmr_mbuf_t* rmr_realloc_payload(rmr_mbuf_t*, int, int, int)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_free_msg(mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_free_msg
+ extern void rmr_free_msg(rmr_mbuf_t* mbuf )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_payload_size(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_payload_size
+ extern int rmr_payload_size(rmr_mbuf_t* msg)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_send_msg(vctx, ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_send_msg
+ extern rmr_mbuf_t* rmr_send_msg(void* vctx, rmr_mbuf_t* msg)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_rcv_msg(vctx, ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_rcv_msg
+ extern rmr_mbuf_t* rmr_rcv_msg(void* vctx, rmr_mbuf_t* old_msg)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_torcv_msg(vctx, ptr_mbuf, ms_to)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_torcv_msg
+ extern rmr_mbuf_t* rmr_torcv_msg(void* vctx, rmr_mbuf_t* old_msg, int ms_to)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_rts_msg(vctx, ptr_mbuf, payload=None, mtype=None)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_rts_msg
+ extern rmr_mbuf_t* rmr_rts_msg(void* vctx, rmr_mbuf_t* msg)
+
+ additional features beyond c-rmr:
+ if payload is not None, attempts to set the payload
+ if mtype is not None, sets the sbuf's message type
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_call(vctx, ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_call
+ extern rmr_mbuf_t* rmr_call(void* vctx, rmr_mbuf_t* msg)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_set_meid(ptr_mbuf, byte_str)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_bytes2meid
+ extern int rmr_bytes2meid(rmr_mbuf_t* mbuf, unsigned char const* src, int len);
+
+ Caution: the meid length supported in an RMR message is 32 bytes, but C applications
+ expect this to be a nil terminated string and thus only 31 bytes are actually available.
+
+ Raises: exceptions.MeidSizeOutOfRang
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_get_meid(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Get the managed equipment ID (meid) from the message header.
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ :Returns:
+
+ string:
+ meid
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: rmr_get_src(ptr_mbuf, dest)
+ :module: ricxappframe.rmr.rmr
+
+
+ Refer to the rmr C documentation for rmr_get_src
+ extern unsigned char* rmr_get_src(rmr_mbuf_t* mbuf, unsigned char* dest);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: get_payload(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Given a rmr_buf_t*, get it's binary payload as a bytes object
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ :Returns:
+
+ bytes:
+ the message payload
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: get_xaction(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ given a rmr_buf_t*, get it's transaction id
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ :Returns:
+
+ bytes:
+ the transaction id
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: message_summary(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Returns a dict that contains the fields of a message
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ :Returns:
+
+ dict:
+ dict message summary
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: set_payload_and_length(byte_str, ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ | Set an rmr payload and content length
+ | In place method, no return
+
+
+ :Parameters:
+
+ **byte_str: bytes**
+ the bytes to set the payload to
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: generate_and_set_transaction_id(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Generate a UUID and Set an rmr transaction id to it
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: set_transaction_id(ptr_mbuf, tid_bytes)
+ :module: ricxappframe.rmr.rmr
+
+
+ Set an rmr transaction id
+ TODO: on next API break, merge these two functions. Not done now to preserve API.
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ **tid_bytes: bytes**
+ bytes of the desired transaction id
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!
+
+.. py:function:: get_src(ptr_mbuf)
+ :module: ricxappframe.rmr.rmr
+
+
+ Get the message source (likely host:port)
+
+
+ :Parameters:
+
+ **ptr_mbuf: ctypes c_void_p**
+ Pointer to an rmr message buffer
+
+ :Returns:
+
+ string:
+ message source
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ..
+ !! processed by numpydoc !!