Add sphinx documentation generation

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>

diff --git a/src/bindings/rmr-python/Changelog.md b/src/bindings/rmr-python/Changelog.md
deleted file mode 100644 (file)
index d729712..0000000
--- a/src/bindings/rmr-python/Changelog.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# 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

diff --git a/src/bindings/rmr-python/Dockerfile-DocGen b/src/bindings/rmr-python/Dockerfile-DocGen
new file mode 100644 (file)
index 0000000..45bb63a
--- /dev/null
+++ b/src/bindings/rmr-python/Dockerfile-DocGen
@@ -0,0 +1,36 @@
+# ==================================================================================
+#       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

diff --git a/src/bindings/rmr-python/README.rst b/src/bindings/rmr-python/README.rst
index cbda718..2f2201d 100644 (file)
--- a/src/bindings/rmr-python/README.rst
+++ b/src/bindings/rmr-python/README.rst
@@ -1,92 +1,17 @@
 rmr-python
 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`

diff --git a/src/bindings/rmr-python/docs/Changelog.rst b/src/bindings/rmr-python/docs/Changelog.rst
new file mode 100644 (file)
index 0000000..3a46b5f
--- /dev/null
+++ b/src/bindings/rmr-python/docs/Changelog.rst
@@ -0,0 +1,205 @@
+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

diff --git a/src/bindings/rmr-python/docs/Makefile b/src/bindings/rmr-python/docs/Makefile
new file mode 100644 (file)
index 0000000..d0c3cbf
--- /dev/null
+++ b/src/bindings/rmr-python/docs/Makefile
@@ -0,0 +1,20 @@
+# 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)

diff --git a/src/bindings/rmr-python/docs/make.bat b/src/bindings/rmr-python/docs/make.bat
new file mode 100644 (file)
index 0000000..6247f7e
--- /dev/null
+++ b/src/bindings/rmr-python/docs/make.bat
@@ -0,0 +1,35 @@
+@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

diff --git a/src/bindings/rmr-python/docs/source/conf.py b/src/bindings/rmr-python/docs/source/conf.py
new file mode 100644 (file)
index 0000000..95d2265
--- /dev/null
+++ b/src/bindings/rmr-python/docs/source/conf.py
@@ -0,0 +1,52 @@
+# 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"]

diff --git a/src/bindings/rmr-python/docs/source/index.rst b/src/bindings/rmr-python/docs/source/index.rst
new file mode 100644 (file)
index 0000000..cbda718
--- /dev/null
+++ b/src/bindings/rmr-python/docs/source/index.rst
@@ -0,0 +1,92 @@
+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

diff --git a/src/bindings/rmr-python/docs/source/module_api.rst b/src/bindings/rmr-python/docs/source/module_api.rst
new file mode 100644 (file)
index 0000000..b0f02f0
--- /dev/null
+++ b/src/bindings/rmr-python/docs/source/module_api.rst
@@ -0,0 +1,19 @@
+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:

diff --git a/src/bindings/rmr-python/rmr/rmr.py b/src/bindings/rmr-python/rmr/rmr.py
index aeb9e18..d1326c0 100644 (file)
--- a/src/bindings/rmr-python/rmr/rmr.py
+++ b/src/bindings/rmr-python/rmr/rmr.py
@@ -83,7 +83,17 @@ def _get_mapping_dict(cache={}):
 
 def _state_to_status(stateno):
     """
 
 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")
     """
     sdict = _get_mapping_dict()
     return sdict.get(stateno, "UNKNOWN STATE")

diff --git a/src/bindings/rmr-python/setup.py b/src/bindings/rmr-python/setup.py
index 2ea41f6..ca2d22e 100644 (file)
--- a/src/bindings/rmr-python/setup.py
+++ b/src/bindings/rmr-python/setup.py
@@ -22,14 +22,14 @@ SETUP_DIR = abspath(dirname(__file__))
 
 def _long_descr():
     """Yields the content of documentation files for the long description"""
 
 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",
     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",
     packages=find_packages(),
     author="Tommy Carpenter, E. Scott Daniels",
     description="Python wrapper for RIC RMR",