This is part 1 of 2 of a change. Part 1 adds a generation process.
Part 2 will make the docstrings more complaint so the generated docs
look nice.
Issue-ID: RICPLT-1611
Change-Id: Ie065affe5a4e2d44182e536f71287b666263de0d
Signed-off-by: Tommy Carpenter <tommy@research.att.com>
+++ /dev/null
-# Change Log
-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/).
-
-## [0.10.5] - 8/13/2019
- * Make the PYPI page for rmr look nicer.
-
-## [0.10.4] - 8/08/2019
- * Fix underlying problem getting errno from some environments; now references new RMR message field to get errno value.
- * Add /usr/local/lib64 to tox environment variable to support systems where libraries natually install in lib64 rather than lib.
-
-## [0.10.3] - 7/31/2019
- * (Correctly) Include license here per Jira RICPLT-1855
-
-## [0.10.2] - 7/31/2019
- * Include license here per Jira RICPLT-1855
-
-## [0.10.0] - 5/15/2019
- * Fix a bug in rmr mock that prevented it for being used for rmr_rcv (was only usable for rmr_torcv)
- * Add more unit tests, esp for message summary
- * Remove meid truncation in the case where a nil is present mid string
- * Change the defaul mock of meid and get_src to something more useful
-
-## [0.9.0] - 5/13/2019
- * Add a new module for mocking out rmr-python, useful for other packages that depend on rmr-python
-
-## [0.8.4] - 5/10/2019
- * Add some unit tests; more to come
-
-## [0.8.3] - 5/8/2019
- * Better loop indexing in meid string handling
-
-## [0.8.2] - 5/8/2019
- * Fix examples bug
- * add liscneses for LF push
-
-## [0.8.1] - 5/7/2019
- * Better andling of meid in message summary
-
-## [0.8.0] - 5/7/2019
- * Refactor some code to be more functional
- * Put back RMR_MAX_RCV_BYTES as a constant
- * Add tox.ini, although right now it only LINTs
-
-## [0.7.0] - 5/6/2019
- * Add constant fetching from RMr library
-
-## [0.6.0] - 5/6/2019
- * Add a new field to rmr_mbuf_t: sub_id
- * Fix prior commits lint-ailing python style
-
-## [0.5.0] - 5/3/2019
- * Add errno access via new function: rmr.errno()
- * Add new functions to access new RMr header fields: get_src, get_meid, rmr_bytes2meid
- * Add new RMr constants for error states
-
-## [0.4.1] - 4/8/2019
- * Fix a non-ascii encoding issue
-
-## [0.4.0] - 3/28/2019
- * Greatly imroved test sender/receiver
- * Three new functions implemented (rmr_close, rmr_set_stimeout, rmr_payload_size)
-
-## [0.3.0] - 3/26/2019
- * Support a new receive function that (hurray!) has a timeout
-
-## [0.2.1] - 3/25/2019
- * Add two new MR states
-
-## [0.2.0] - 3/25/2019
- * Switch to NNG from nanomessage
-
-## [0.1.0] - 3/14/2019
- * Initial Creation
--- /dev/null
+# ==================================================================================
+# 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.
+# ==================================================================================
+FROM python:3.7-alpine
+
+# copy NNG and rmr out of the CI builder nng
+# NOTE: rmr-pythons documentation does not change based on what version of rmr is installed, only based on what version rmr-python was built (coding wise) against last, so it doesn't matter if the rmr in the parent repo here is ahead
+COPY --from=nexus3.o-ran-sc.org:10004/bldr-alpine3:3-a3.9 /usr/local/lib64/libnng.so /usr/local/lib64/libnng.so
+COPY --from=nexus3.o-ran-sc.org:10004/bldr-alpine3:3-a3.9 /usr/local/lib64/librmr_nng.so /usr/local/lib64/librmr_nng.so
+
+COPY rmr/ /tmp/rmr
+COPY docs/ /tmp/docs
+WORKDIR /tmp
+
+# need make for sphinx
+RUN apk add --update make
+
+RUN pip install sphinx numpydoc
+
+WORKDIR /tmp/docs/
+ENV LD_LIBRARY_PATH /usr/local/lib/:/usr/local/lib64
+# text generates the documentation in text format
+CMD make text
rmr-python
-==========
+===========
-Summary, Limitations
-====================
+Please see `docs/source/index.rst`
-This is a CTYPES wrapper around the C rmr library. It requires you have
-rmr installed.
+Generating Documentation
+========================
-That is, it is not a native re-implementation of the rmr library. This
-seems to come with pros and cons. On the positive side, wrapping the
-library was much less work; we only need to wrap the function
-signatures. Keeping up with the rmr spec is thus also less work, as when
-new functions are added into the C lib, we only need to again wrap the
-function signatures.
-
-The downside is this seems to be Linux only currently. This wrapper
-immediately SIGABRT’s on Mac, and no one yet seems to know why. The
-other downside is that there are currently some functionality that needs
-to be “exported” from the C library for this to be fully operational.
-For example, CTYPES does not have access to C header files, and
-important constants are defined in the C header files.
-
-Possibly evaluate whether we could natively reimplement the API with the nano nng python
-bindings: https://pypi.org/project/pynng/
-
-Not Yet Implemented
--------------------
-
-At the time of this writing (Aug 13 2019) The following C functions
-are not yet implemented in this library (do we need them?):
+To generate `rmr-python` documentation:
::
- 1. `extern void rmr_free_msg`
- 2. `extern rmr_mbuf_t* rmr_mtosend_msg`
- 3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott)
- 4. `extern rmr_mbuf_t* rmr_rcv_specific`
- 5. `extern int rmr_get_rcvfd`
-
-Unit Testing
-============
-
-::
-
- tox
- open htmlcov/index.html
-
-Installation
-============
-
-Prequisites
------------
-
-If rmr is *not* compiled on your system, see the below instructions for
-downloading and compiling rmr. This library expects that the rmr .so
-files are compiled and available.
-
-From PyPi
----------
-
-::
-
- pip install rmr==X.Y.Z
-
-From Source
------------
-
-::
-
- git clone "https://gerrit.o-ran-sc.org/r/ric-plt/lib/rmr"
- cd rmr/src/bindings/rmr-python/
- pip install .
-
-Examples
-========
-
-See the ``examples`` directory.
-
-Compiling rmr (if not already done on your system)
-==================================================
-
-(Note, you may or may not need sudo in your final command, depending on
-permissions to ``/usr/local``. The pack externals option to CMake is
-needed only if the NNG libary is not already installed on the system,
-and you do not wish to manually install it.)
-
-::
+ # from the root of rmr-python, not here
+ docker build -t rmrpythondocs:latest -f Dockerfile-DocGen .
+ docker run -v ~/desired/target/dir/:/tmp/docs/build/text rmrpythondocs:latest
- git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr
- cd rmr
- mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install
+After running this, `/desired/target/dir/` will contain `index.rst` and `module_api.txt`
--- /dev/null
+Change Log
+==========
+
+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/>`__.
+
+[0.10.6] - 8/13/2019
+--------------------
+
+::
+ * Moves Changelog.md to this file, to be consistent with rst-ification
+ * Sets up a Dockerfile to generate documentation for rmr-python using sphinx
+
+
+[0.10.5] - 8/13/2019
+--------------------
+
+::
+
+ * Make the PYPI page for rmr look nicer.
+
+.. _section-1:
+
+[0.10.4] - 8/08/2019
+--------------------
+
+::
+
+ * Fix underlying problem getting errno from some environments; now references new RMR message field to get errno value.
+ * Add /usr/local/lib64 to tox environment variable to support systems where libraries natually install in lib64 rather than lib.
+
+.. _section-2:
+
+[0.10.3] - 7/31/2019
+--------------------
+
+::
+
+ * (Correctly) Include license here per Jira RICPLT-1855
+
+.. _section-3:
+
+[0.10.2] - 7/31/2019
+--------------------
+
+::
+
+ * Include license here per Jira RICPLT-1855
+
+.. _section-4:
+
+[0.10.0] - 5/15/2019
+--------------------
+
+::
+
+ * Fix a bug in rmr mock that prevented it for being used for rmr_rcv (was only usable for rmr_torcv)
+ * Add more unit tests, esp for message summary
+ * Remove meid truncation in the case where a nil is present mid string
+ * Change the defaul mock of meid and get_src to something more useful
+
+.. _section-5:
+
+[0.9.0] - 5/13/2019
+-------------------
+
+::
+
+ * Add a new module for mocking out rmr-python, useful for other packages that depend on rmr-python
+
+.. _section-6:
+
+[0.8.4] - 5/10/2019
+-------------------
+
+::
+
+ * Add some unit tests; more to come
+
+.. _section-7:
+
+[0.8.3] - 5/8/2019
+------------------
+
+::
+
+ * Better loop indexing in meid string handling
+
+.. _section-8:
+
+[0.8.2] - 5/8/2019
+------------------
+
+::
+
+ * Fix examples bug
+ * add liscneses for LF push
+
+.. _section-9:
+
+[0.8.1] - 5/7/2019
+------------------
+
+::
+
+ * Better andling of meid in message summary
+
+.. _section-10:
+
+[0.8.0] - 5/7/2019
+------------------
+
+::
+
+ * Refactor some code to be more functional
+ * Put back RMR_MAX_RCV_BYTES as a constant
+ * Add tox.ini, although right now it only LINTs
+
+.. _section-11:
+
+[0.7.0] - 5/6/2019
+------------------
+
+::
+
+ * Add constant fetching from RMr library
+
+.. _section-12:
+
+[0.6.0] - 5/6/2019
+------------------
+
+::
+
+ * Add a new field to rmr_mbuf_t: sub_id
+ * Fix prior commits lint-ailing python style
+
+.. _section-13:
+
+[0.5.0] - 5/3/2019
+------------------
+
+::
+
+ * Add errno access via new function: rmr.errno()
+ * Add new functions to access new RMr header fields: get_src, get_meid, rmr_bytes2meid
+ * Add new RMr constants for error states
+
+.. _section-14:
+
+[0.4.1] - 4/8/2019
+------------------
+
+::
+
+ * Fix a non-ascii encoding issue
+
+.. _section-15:
+
+[0.4.0] - 3/28/2019
+-------------------
+
+::
+
+ * Greatly imroved test sender/receiver
+ * Three new functions implemented (rmr_close, rmr_set_stimeout, rmr_payload_size)
+
+.. _section-16:
+
+[0.3.0] - 3/26/2019
+-------------------
+
+::
+
+ * Support a new receive function that (hurray!) has a timeout
+
+.. _section-17:
+
+[0.2.1] - 3/25/2019
+-------------------
+
+::
+
+ * Add two new MR states
+
+.. _section-18:
+
+[0.2.0] - 3/25/2019
+-------------------
+
+::
+
+ * Switch to NNG from nanomessage
+
+.. _section-19:
+
+[0.1.0] - 3/14/2019
+-------------------
+
+::
+
+ * Initial Creation
--- /dev/null
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
--- /dev/null
+@ECHO OFF\r
+\r
+pushd %~dp0\r
+\r
+REM Command file for Sphinx documentation\r
+\r
+if "%SPHINXBUILD%" == "" (\r
+ set SPHINXBUILD=sphinx-build\r
+)\r
+set SOURCEDIR=source\r
+set BUILDDIR=build\r
+\r
+if "%1" == "" goto help\r
+\r
+%SPHINXBUILD% >NUL 2>NUL\r
+if errorlevel 9009 (\r
+ echo.\r
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx\r
+ echo.installed, then set the SPHINXBUILD environment variable to point\r
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you\r
+ echo.may add the Sphinx directory to PATH.\r
+ echo.\r
+ echo.If you don't have Sphinx installed, grab it from\r
+ echo.http://sphinx-doc.org/\r
+ exit /b 1\r
+)\r
+\r
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%\r
+goto end\r
+\r
+:help\r
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%\r
+\r
+:end\r
+popd\r
--- /dev/null
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "rmr-python"
+copyright = "2019, Tommy Carpenter, Scott E Daniels"
+author = "Tommy Carpenter, Scott E Daniels"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "numpydoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
--- /dev/null
+rmr-python
+==========
+
+Summary, Limitations
+====================
+
+This is a CTYPES wrapper around the C rmr library. It requires you have
+rmr installed.
+
+That is, it is not a native re-implementation of the rmr library. This
+seems to come with pros and cons. On the positive side, wrapping the
+library was much less work; we only need to wrap the function
+signatures. Keeping up with the rmr spec is thus also less work, as when
+new functions are added into the C lib, we only need to again wrap the
+function signatures.
+
+The downside is this seems to be Linux only currently. This wrapper
+immediately SIGABRT’s on Mac, and no one yet seems to know why. The
+other downside is that there are currently some functionality that needs
+to be “exported” from the C library for this to be fully operational.
+For example, CTYPES does not have access to C header files, and
+important constants are defined in the C header files.
+
+Possibly evaluate whether we could natively reimplement the API with the nano nng python
+bindings: https://pypi.org/project/pynng/
+
+Not Yet Implemented
+-------------------
+
+At the time of this writing (Aug 13 2019) The following C functions
+are not yet implemented in this library (do we need them?):
+
+::
+
+ 1. `extern void rmr_free_msg`
+ 2. `extern rmr_mbuf_t* rmr_mtosend_msg`
+ 3. `extern rmr_mbuf_t* rmr_call` (this has some problems AFAIU from Scott)
+ 4. `extern rmr_mbuf_t* rmr_rcv_specific`
+ 5. `extern int rmr_get_rcvfd`
+
+Unit Testing
+============
+
+::
+
+ tox
+ open htmlcov/index.html
+
+Installation
+============
+
+Prequisites
+-----------
+
+If rmr is *not* compiled on your system, see the below instructions for
+downloading and compiling rmr. This library expects that the rmr .so
+files are compiled and available.
+
+From PyPi
+---------
+
+::
+
+ pip install rmr==X.Y.Z
+
+From Source
+-----------
+
+::
+
+ git clone "https://gerrit.o-ran-sc.org/r/ric-plt/lib/rmr"
+ cd rmr/src/bindings/rmr-python/
+ pip install .
+
+Examples
+========
+
+See the ``examples`` directory.
+
+Compiling rmr (if not already done on your system)
+==================================================
+
+(Note, you may or may not need sudo in your final command, depending on
+permissions to ``/usr/local``. The pack externals option to CMake is
+needed only if the NNG libary is not already installed on the system,
+and you do not wish to manually install it.)
+
+::
+
+ git clone https://gerrit.oran-osc.org/r/ric-plt/lib/rmr
+ cd rmr
+ mkdir .build; cd .build; cmake .. -DPACK_EXTERNALS=1; sudo make install
--- /dev/null
+rmr-python's Module Index
+==========================
+
+rmr.rmr module
+--------------
+
+.. automodule:: rmr.rmr
+ :members:
+ :undoc-members:
+ :private-members:
+
+
+rmr.rmr\_mocks.rmr\_mocks module
+--------------------------------
+
+.. automodule:: rmr.rmr_mocks.rmr_mocks
+ :members:
+ :undoc-members:
+ :private-members:
def _state_to_status(stateno):
"""
- convery a msg state to status
+ Convert a msg state to status
+
+ Parameters
+ ----------
+ stateno: int
+ the state of the rmr message buffer
+
+ Returns
+ -------
+ string
+ the cooresponding message state
"""
sdict = _get_mapping_dict()
return sdict.get(stateno, "UNKNOWN STATE")
def _long_descr():
"""Yields the content of documentation files for the long description"""
- doc_path = path_join(SETUP_DIR, "README.rst")
+ doc_path = path_join(SETUP_DIR, "docs/source/index.rst")
with open(doc_path) as f:
return f.read()
setup(
name="rmr",
- version="0.10.5",
+ version="0.10.6",
packages=find_packages(),
author="Tommy Carpenter, E. Scott Daniels",
description="Python wrapper for RIC RMR",
Code Review / ric-plt / lib / rmr.git / commitdiff