From 0cb4b57403307f128b3597a52fa77cbc8524f078 Mon Sep 17 00:00:00 2001 From: Tommy Carpenter Date: Tue, 13 Aug 2019 16:02:42 -0400 Subject: [PATCH] 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 --- src/bindings/rmr-python/Changelog.md | 76 -------- src/bindings/rmr-python/Dockerfile-DocGen | 36 ++++ src/bindings/rmr-python/README.rst | 93 +--------- src/bindings/rmr-python/docs/Changelog.rst | 205 +++++++++++++++++++++ src/bindings/rmr-python/docs/Makefile | 20 ++ src/bindings/rmr-python/docs/make.bat | 35 ++++ src/bindings/rmr-python/docs/source/conf.py | 52 ++++++ src/bindings/rmr-python/docs/source/index.rst | 92 +++++++++ src/bindings/rmr-python/docs/source/module_api.rst | 19 ++ src/bindings/rmr-python/rmr/rmr.py | 12 +- src/bindings/rmr-python/setup.py | 4 +- 11 files changed, 481 insertions(+), 163 deletions(-) delete mode 100644 src/bindings/rmr-python/Changelog.md create mode 100644 src/bindings/rmr-python/Dockerfile-DocGen create mode 100644 src/bindings/rmr-python/docs/Changelog.rst create mode 100644 src/bindings/rmr-python/docs/Makefile create mode 100644 src/bindings/rmr-python/docs/make.bat create mode 100644 src/bindings/rmr-python/docs/source/conf.py create mode 100644 src/bindings/rmr-python/docs/source/index.rst create mode 100644 src/bindings/rmr-python/docs/source/module_api.rst diff --git a/src/bindings/rmr-python/Changelog.md b/src/bindings/rmr-python/Changelog.md deleted file mode 100644 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 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 --- a/src/bindings/rmr-python/README.rst +++ b/src/bindings/rmr-python/README.rst @@ -1,92 +1,17 @@ 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 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 `__ +and this project adheres to `Semantic +Versioning `__. + +[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 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 index 0000000..6247f7e --- /dev/null +++ b/src/bindings/rmr-python/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/src/bindings/rmr-python/docs/source/conf.py b/src/bindings/rmr-python/docs/source/conf.py new file mode 100644 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 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 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 --- 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): """ - 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") diff --git a/src/bindings/rmr-python/setup.py b/src/bindings/rmr-python/setup.py index 2ea41f6..ca2d22e 100644 --- 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""" - 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", -- 2.16.6