Add root level docs control files
Several control files must exist at the repo root, not in
docs, in order to vet and push the documentation out to some
remote site. This changes adds those files, and fixes the
formatting issues that RST vetting is complaining about.
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: Ibeda532f0524d5f5d4d138ece4e9265429fa322b
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..44c62b3
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,42 @@
+# vim: ts=4 expandtab sw=4:
+#==================================================================================
+# 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.
+#==================================================================================
+
+# NOTE: this exists only to support the RTD scraper(s). Future: change requirements
+# so this can be moved inside of docs/ rather than polluting the top level.
+
+---
+# .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
+
diff --git a/README b/README
index f3772d4..0f283f6 100644
--- a/README
+++ b/README
@@ -58,3 +58,17 @@
test All unit and application level tests for the core library are kept
within this directory. Tests for bindings are managed within the
binding's directory under the source directory.
+
+Top level pollution
+There are several "configuration" files which sit at the top level of the
+repo that are required for some sort of CI/CD/Documentation automation. Most,
+if not all of the CI/CD goo is in the ci directory where it's out of the way
+and thus not confusing. However, there is some pollution that can generally
+be ignored:
+
+ tox.ini -- this seems to drive the scraper which pulls from docs and
+ writes to some external documentation repo/host.
+
+
+ .readthedocs.yaml -- this seems to be some configuration for the docs
+ scraping process(es).
diff --git a/doc/src/generic_ps.im b/doc/src/generic_ps.im
index f300c05..9020b91 100644
--- a/doc/src/generic_ps.im
+++ b/doc/src/generic_ps.im
@@ -20,6 +20,8 @@
.** macros compatable with the roff/troff and rts imbed files
.** this is included when generating postscript from the man source.
+ .dv esc : .** rst needs an escape for some things
+
.hn off
.dv text_size 10p
.dv ex_size 8p
diff --git a/doc/src/man/rmr_bytes2payload.3.xfm b/doc/src/man/rmr_bytes2payload.3.xfm
index 74bc4fc..9deeef4 100644
--- a/doc/src/man/rmr_bytes2payload.3.xfm
+++ b/doc/src/man/rmr_bytes2payload.3.xfm
@@ -46,9 +46,9 @@
&h2(DESCRIPTION)
This is a convenience function as some wrapper languages might not have the ability to
directly copy into the payload buffer.
-The bytes from &ital( src ) for the length given are copied to the payload.
+The bytes from &ital(src) for the length given are copied to the payload.
It is the caller's responsibility to ensure that the payload is large enough.
-Upon successfully copy, the &cw( len ) field in the message buffer is updated to
+Upon successfully copy, the &cw(len) field in the message buffer is updated to
reflect the number of bytes copied.
.sp
There is little error checking, and no error reporting.
diff --git a/doc/src/man/rmr_get_meid.3.xfm b/doc/src/man/rmr_get_meid.3.xfm
index 3980542..d31bb3c 100644
--- a/doc/src/man/rmr_get_meid.3.xfm
+++ b/doc/src/man/rmr_get_meid.3.xfm
@@ -46,18 +46,18 @@
&h2(DESCRIPTION)
The &cw(rmr_get_meid) function will copy the managed equipment ID (meid) field from the message
into the &ital(dest) buffer provided by the user.
-The buffer referenced by &ital( dest ) is assumed to be at least &cw(RMR_MAX_MEID) bytes in length.
-If &ital( dest ) is NULL, then a buffer is allocated (the calling application is expected
+The buffer referenced by &ital(dest) is assumed to be at least &cw(RMR_MAX_MEID) bytes in length.
+If &ital(dest) is NULL, then a buffer is allocated (the calling application is expected
to free when the buffer is no longer needed).
&h2(RETURN VALUE)
On success, a pointer to the extracted string is returned.
-If &ital( dest ) was supplied, then this is just a pointer to the caller's buffer.
-If &ital( dest ) was NULL, this is a pointer to the allocated buffer.
+If &ital(dest) was supplied, then this is just a pointer to the caller's buffer.
+If &ital(dest) was NULL, this is a pointer to the allocated buffer.
If an error occurs, a nil pointer is returned and errno is set as described below.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw( errno ) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
@@ -65,7 +65,7 @@
&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&half_space
-&di(ENOMEM) A nil pointer was passed for &ital( dest, ) however it was not possible to allocate a
+&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
buffer using malloc().
&end_dlist
diff --git a/doc/src/man/rmr_get_srcip.3.xfm b/doc/src/man/rmr_get_srcip.3.xfm
index 489d1e5..9e3103b 100644
--- a/doc/src/man/rmr_get_srcip.3.xfm
+++ b/doc/src/man/rmr_get_srcip.3.xfm
@@ -62,7 +62,7 @@
On failure, a nil pointer is returned and the value of errno is set.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw( errno ) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
diff --git a/doc/src/man/rmr_get_xact.3.xfm b/doc/src/man/rmr_get_xact.3.xfm
index 8674702..6506614 100644
--- a/doc/src/man/rmr_get_xact.3.xfm
+++ b/doc/src/man/rmr_get_xact.3.xfm
@@ -46,18 +46,18 @@
&h2(DESCRIPTION)
The &cw(rmr_get_xact) function will copy the transaction field from the message
into the &ital(dest) buffer provided by the user.
-The buffer referenced by &ital( dest ) is assumed to be at least &cw(RMR_MAX_XID) bytes in length.
-If &ital( dest ) is NULL, then a buffer is allocated (the calling application is expected
+The buffer referenced by &ital(dest) is assumed to be at least &cw(RMR_MAX_XID) bytes in length.
+If &ital(dest) is NULL, then a buffer is allocated (the calling application is expected
to free when the buffer is no longer needed).
&h2(RETURN VALUE)
On success, a pointer to the extracted string is returned.
-If &ital( dest ) was supplied, then this is just a pointer to the caller's buffer.
-If &ital( dest ) was NULL, this is a pointer to the allocated buffer.
+If &ital(dest) was supplied, then this is just a pointer to the caller's buffer.
+If &ital(dest) was NULL, this is a pointer to the allocated buffer.
If an error occurs, a nil pointer is returned and errno is set as described below.
&h2(ERRORS)
-If an error occurs, the value of the global variable &cw( errno ) will be set to one of
+If an error occurs, the value of the global variable &cw(errno) will be set to one of
the following with the indicated meaning.
&beg_dlist(.75i : ^&bold_font )
@@ -65,7 +65,7 @@
&di(EINVAL) The message, or an internal portion of the message, was corrupted or the pointer was invalid.
&half_space
-&di(ENOMEM) A nil pointer was passed for &ital( dest, ) however it was not possible to allocate a
+&di(ENOMEM) A nil pointer was passed for &ital(dest,) however it was not possible to allocate a
buffer using malloc().
&end_dlist
diff --git a/doc/src/man/rmr_init.3.xfm b/doc/src/man/rmr_init.3.xfm
index 488e6d2..5413beb 100644
--- a/doc/src/man/rmr_init.3.xfm
+++ b/doc/src/man/rmr_init.3.xfm
@@ -57,7 +57,7 @@
&space
&ital(Flags) allows for selection of some RMr options at the time of initialisation.
-These are set by ORing &cw(RMRFL_) constants from the RMr header file. Currently the
+These are set by ORing &cw(RMRFL) constants from the RMr header file. Currently the
following flags are supported:
&half_space
@@ -83,7 +83,7 @@
Multi-threaded call support adds the ability for a user application with multiple threads
to invoke a blocking call function with the guarentee that the correct response message
is delivered to the thread.
-The additional support is implemented with the &ital( rmr_mt_call() ) and &ital( rmr_mt_rcv() )
+The additional support is implemented with the &ital(rmr_mt_call()) and &ital(rmr_mt_rcv())
function calls.
&space
diff --git a/doc/src/man/rmr_init_trace.3.xfm b/doc/src/man/rmr_init_trace.3.xfm
index f31baf0..9168c68 100644
--- a/doc/src/man/rmr_init_trace.3.xfm
+++ b/doc/src/man/rmr_init_trace.3.xfm
@@ -66,7 +66,7 @@
&h2(RETURN VALUE)
A value of 1 is returned on success, and 0 on failure. A failure indicates that the
-RMr context (void *) passed to this function was not valid.
+RMr context (a void pointer passed to this function was not valid.
&h2(SEE ALSO )
.ju off
diff --git a/doc/src/man/rmr_mt_call.3.xfm b/doc/src/man/rmr_mt_call.3.xfm
index 76d209f..6ba797d 100644
--- a/doc/src/man/rmr_mt_call.3.xfm
+++ b/doc/src/man/rmr_mt_call.3.xfm
@@ -50,12 +50,12 @@
The user application supplies a completed message buffer, as it would for
a &cw(rmr_send_msg) call, but unlike with a send, the buffer returned will have
the response from the application that received the message.
-The thread invoking the &ital( rmr_mt_call()) will block until a message arrives
+The thread invoking the &ital(rmr_mt_call()) will block until a message arrives
or until &ital(timeout) milliseconds has passed; which ever comes first.
Using a timeout value of zero (0) will cause the thread to block without a timeout.
&space
-The &ital( id ) supplied as the third parameter is an integer in the range of 2 through
+The &ital(id) supplied as the third parameter is an integer in the range of 2 through
255 inclusive.
This is a caller defined "thread number" and is used to match the response message
with the correct user application thread.
@@ -64,7 +64,7 @@
&space
Messages which are received while waiting for the response are queued on a &ital(normal)
receive queue and will be delivered to the user application with the next invocation
-of &ital( rmr_mt_rcv() ) or &ital( rmr_rvv_msg().)
+of &ital(rmr_mt_rcv()) or &ital(rmr_rvv_msg().)
by RMR, and are returned to the user application when &cw(rmr_rcv_msg) is
invoked.
These messages are returned in th order received, one per call to &cw(rmr_rcv_msg.)
@@ -84,7 +84,7 @@
that they are set correctly to avoid missing the response message.
(The application which returns the response message is also expected to ensure that
the return buffer has the matching transaction ID. This can be done transparently if
-the application uses the &ital( rmr_rts_msg() ) function and does not adjust the
+the application uses the &ital(rmr_rts_msg()) function and does not adjust the
transaction ID.
.** pull in common retry text
diff --git a/doc/src/man/rmr_mt_rcv.3.xfm b/doc/src/man/rmr_mt_rcv.3.xfm
index d5c31b2..9584c49 100644
--- a/doc/src/man/rmr_mt_rcv.3.xfm
+++ b/doc/src/man/rmr_mt_rcv.3.xfm
@@ -114,7 +114,7 @@
&half_space
&di(RMR_ERR_NOTSUPP) The multi-threaded option was not enabled when RMr was
-initialised. See the man page for &ital(rmr_init() ) for details.
+initialised. See the man page for &ital(rmr_init()) for details.
&half_space
&di(RMR_ERR_RCVFAILED) A hard error occurred preventing the receive from completing.
diff --git a/doc/src/man/rmr_send_msg.3.xfm b/doc/src/man/rmr_send_msg.3.xfm
index d9cc620..36812c0 100644
--- a/doc/src/man/rmr_send_msg.3.xfm
+++ b/doc/src/man/rmr_send_msg.3.xfm
@@ -67,7 +67,7 @@
&space
When the message cannot be successfully sent this function will return the unsent (original)
message buffer with the state set to indicate the reason for failure.
-The value of &ital( errno ) may also be set to reflect a more detailed failure reason if it
+The value of &ital(errno) may also be set to reflect a more detailed failure reason if it
is known.
&space
diff --git a/doc/src/man/rmr_set_stimeout.3.xfm b/doc/src/man/rmr_set_stimeout.3.xfm
index ca091ac..4f5dd35 100644
--- a/doc/src/man/rmr_set_stimeout.3.xfm
+++ b/doc/src/man/rmr_set_stimeout.3.xfm
@@ -44,35 +44,35 @@
&h2(DESCRIPTION)
The &cw(rmr_set_stimeout) function sets the configuration for how RMr will retry
-message send operations which complete with either a &ital( timeout ) or &ital( again )
+message send operations which complete with either a &ital(timeout) or &ital(again)
completion value. (Send operations include all of the possible message send
-functions: &ital( rmr_send_msg(), rmr_call(), rmr_rts_msg() ) and &ital( rmr_wh_send_msg(). )
-The &ital( rloops ) parameter sets the maximum number of retry loops
+functions: &ital(rmr_send_msg(), rmr_call(), rmr_rts_msg()) and &ital(rmr_wh_send_msg().)
+The &ital(rloops) parameter sets the maximum number of retry loops
that will be attempted before giving up and returning the unsuccessful state to the user
application.
-Each retry loop is approximately 1000 attempts, and RMr does &bold( not ) invoke any sleep
+Each retry loop is approximately 1000 attempts, and RMr does &bold(not) invoke any sleep
function between retries in the loop; a small, 1 mu-sec, sleep is executed between loop
-sets if the &ital( rloops ) value is greater than 1.
+sets if the &ital(rloops) value is greater than 1.
.sp
&h3(Disabling Retries)
-By default, the send operations will execute with an &ital( rloop ) setting of 1; each send
+By default, the send operations will execute with an &ital(rloop) setting of 1; each send
operation will attempt to resend the message approximately 1000 times before giving up.
If the user application does not want to have send operations retry when the underlying
-transport mechanism indicates &ital( timeout ) or &ital( again, ) the application should
-invoke this function and pass a value of 0 (zero) for &ital( rloops. )
-With this setting, all RMr send operations will attempt a send operation only &bold( once, )
+transport mechanism indicates &ital(timeout) or &ital(again,) the application should
+invoke this function and pass a value of 0 (zero) for &ital(rloops.)
+With this setting, all RMr send operations will attempt a send operation only &bold(once,)
returning immediately to the caller with the state of that single attempt.
&h2(RETURN VALUE)
-This function returns a -1 to indicate that the &ital( rloops ) value could not be set, and
-the value &ital( RMR_OK ) to indicate success.
+This function returns a -1 to indicate that the &ital(rloops) value could not be set, and
+the value &ital(RMR_OK) to indicate success.
&h2(ERRORS)
-Currently errno is &bold( not ) set by this function; the only cause of a failure is an
-invalid context ( .sm &ital( vctx ) .sm ) pointer.
+Currently errno is &bold(not) set by this function; the only cause of a failure is an
+invalid context ( .sm &ital(vctx) .sm ) pointer.
&h2(EXAMPLE)
The following is a simple example of how the &cw(rmr_set_stimeout) function is called.
diff --git a/doc/src/man/rmr_str2meid.3.xfm b/doc/src/man/rmr_str2meid.3.xfm
index 5d336b6..28f85c6 100644
--- a/doc/src/man/rmr_str2meid.3.xfm
+++ b/doc/src/man/rmr_str2meid.3.xfm
@@ -48,7 +48,7 @@
managed equipment ID (meid) field in the given message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_MEID) and if string length is larger
than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the
-behaviour of the &cw( lrmr_bytes2meid() ) function.)
+behaviour of the &cw(lrmr_bytes2meid()) function.)
&h2(RETURN VALUE)
On success, the value RMR_OK is returned.
diff --git a/doc/src/man/rmr_str2xact.3.xfm b/doc/src/man/rmr_str2xact.3.xfm
index 6f6046f..e27c5f6 100644
--- a/doc/src/man/rmr_str2xact.3.xfm
+++ b/doc/src/man/rmr_str2xact.3.xfm
@@ -48,7 +48,7 @@
transaction ID (xaction) field in the given message.
The field is a fixed length, gated by the constant &cw(RMR_MAX_XID) and if string length is larger
than this value, then &bold(nothing) will be copied. (Note, this differs slightly from the
-behaviour of the &cw( lrmr_bytes2xact() ) function.)
+behaviour of the &cw(lrmr_bytes2xact()) function.)
&beg_dlist(.75i : ^&bold_font )
&h2(RETURN VALUE)
diff --git a/doc/src/markdown.im b/doc/src/markdown.im
index d922fc9..17ae572 100644
--- a/doc/src/markdown.im
+++ b/doc/src/markdown.im
@@ -37,6 +37,7 @@
.hn off
+.dv esc : .** rst needs an escape for some things
.** these macros are common for prfm/tfm, markdown will override some
.dv indent .ll -.5i .in +.25i
diff --git a/doc/src/roff.im b/doc/src/roff.im
index eef25de..4c00d23 100644
--- a/doc/src/roff.im
+++ b/doc/src/roff.im
@@ -50,6 +50,8 @@
.dv center_start .br ^^.ce 999
.dv center_end .br ^.ce 0
+.dv esc : .** rst needs an escape for some things
+
.dv line_len ^^.ll $1
.dv space .br ^^.sp 1 .br
.dv half_space .br ^^.sp 1 .br
diff --git a/doc/src/rst.im b/doc/src/rst.im
index ebbbefe..e2444b1 100644
--- a/doc/src/rst.im
+++ b/doc/src/rst.im
@@ -62,6 +62,7 @@
.in 0i .** bloody rst is indention sensitive like markdown; sheesh
+ .dv esc \ : .** bloody need to escape _ and * at the end of a word
.dv line_len .ll $1
.dv space .sp 1
.dv half_space .sp 1
diff --git a/doc/src/rtd/Makefile b/doc/src/rtd/Makefile
index 7e49946..4c64278 100644
--- a/doc/src/rtd/Makefile
+++ b/doc/src/rtd/Makefile
@@ -37,7 +37,6 @@
docs = config-deploy developer-guide user-guide rel-notes overview
all:: $(docs:%=%.rst) $(docs:%=%.txt) $(docs:%=%.md)
- echo ">>> rm rel-notes.xfm"
rel-notes.xfm:
ksh fmt_changes.ksh >rel-notes.xfm
diff --git a/doc/src/rtd/README b/doc/src/rtd/README
index b6f4acd..c7dd309 100644
--- a/doc/src/rtd/README
+++ b/doc/src/rtd/README
@@ -15,3 +15,11 @@
composition language is far better at geneating readable Postscript
output with embedded figures as well as text and tables.
+CAUTION:
+The RST syntax is as bad as python when it comes to dealing with
+spaces. For example &bold( foo ) will insert spaces after the initial
+bold trigger, and before the trailing bold trigger which will throw
+the tox validation into a tizzy. Further, something like 'void *'
+and 'rmr_ ' does as well. If needed, use the defined escape macro
+to add an escape in such situations; it should only generate for RST
+and not impact other output formats.
diff --git a/doc/src/rtd/developer-guide.xfm b/doc/src/rtd/developer-guide.xfm
index 3cf3bb8..ebde32a 100644
--- a/doc/src/rtd/developer-guide.xfm
+++ b/doc/src/rtd/developer-guide.xfm
@@ -78,7 +78,7 @@
depending on referencing the internal functions during linking.
While this is an infrequently used approach, it does mean that there are very
few functions visible for the user application to reference, all of them having
-the prefix &cw(rmr_,) while allowing internal functions to have shorter names
+the prefix &cw(rmr&{esc}_,) while allowing internal functions to have shorter names
while still being meaningful.
&h2(Coding Style)
diff --git a/doc/src/txt.im b/doc/src/txt.im
index 6599928..bed0d9c 100644
--- a/doc/src/txt.im
+++ b/doc/src/txt.im
@@ -57,6 +57,8 @@
.dv lic2 +
.dv lic3 -
+.dv esc : .** rst needs an escape for some things
+
.dv line_len .ll $1
.dv space .sp 1
.dv mult_space .sp $1
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644
index 0000000..e54843d
--- /dev/null
+++ b/docs/_static/logo.png
Binary files differ
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index 151a6f4..de2bea7 100644
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -24,7 +24,7 @@
There currently is one set of cross languages bindings
supporting Python, and a developer wishing to contribute to
the bindings source should be familiar with Python (version
-3.7+) and with the Ptyhhon *ctypes* library.
+3.7+) and with the Python *ctypes* library.
Code Structure
--------------------------------------------------------------------------------------------
@@ -32,7 +32,7 @@
RMR is designed to provide an insulation layer between user
applications and the actual transport mechanism. Initially
RMR was built on top of Nanosmg, and shortly after was ported
-to NNG (Nanomsg Next Generation). Becuase RMR presents the
+to NNG (Nanomsg Next Generation). Because RMR presents the
same API to the user application regardless of the underlying
transport library, the resulting output when compiling RMR is
a transport specific library. As an example, librmr_nng.a is
@@ -51,8 +51,8 @@
nano
Source which is tightly coupled with the underlying
- Nanomsg library. (Nanomsg has been dreprecated, but the
- RMR source remains as an example.)
+ Nanomsg library. (Nanomsg has been deprecated, but the RMR
+ source remains as an example.)
nng
@@ -65,16 +65,16 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The decision to limit as much as practical the exposure of
-truely interal RMR functions was made, and as a result most
+truely internal RMR functions was made, and as a result most
of the RMR functions carry a static label. In order to
-modularlise the code as much as possible, this means that the
-primary module (e.g. rmr_nng.c) will driectly include other
-RMR modules, rather than depending on referencing the interal
-functions during linking. While this is an infrequenly used
-approach, it does mean that there are very few functions
-visible for the user application to reference, all of them
-having the prefix rmr_, while allowing internal functions to
-have shorter names while still being meaningful.
+modularise the code as much as possible, this means that the
+primary module (e.g. rmr_nng.c) will directly include other
+RMR modules, rather than depending on referencing the
+internal functions during linking. While this is an
+infrequently used approach, it does mean that there are very
+few functions visible for the user application to reference,
+all of them having the prefix rmr\_, while allowing internal
+functions to have shorter names while still being meaningful.
Coding Style
--------------------------------------------------------------------------------------------
@@ -83,7 +83,7 @@
directory, and as such they are not expanded upon here. The
general practice is to follow the style when editing an
existing module, respect the author's choice where style
-alternatves are not frowned upon. When creating new modules,
+alternatives are not frowned upon. When creating new modules,
select a style that fits the guidelines and is easy for you
to work with. There are a few things that are insisted on by
the maintainers of RMR, but for the most part style is up to
diff --git a/docs/index.rst b/docs/index.rst
index c9289fb..361e011 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,6 +3,8 @@
.. who in bloody hell knows what format this should be; guessing!
+.. it does seem though that every .rst file in the directory must be listed here
+.. or tox will complain and fail.
RIC Message Router -- RMR
@@ -15,6 +17,7 @@
overview.rst
config-deploy.rst
+ user-guide.rst
developer-guide.rst
rel-notes.rst
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
deleted file mode 100644
index 67c3e88..0000000
--- a/docs/release-notes.rst
+++ /dev/null
@@ -1,155 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. SPDX-License-Identifier: CC-BY-4.0
-
-RIC Dashboard Release Notes
-===========================
-
-Version 1.3.0, 4 Nov 2019
--------------------------
-* Revise e2-mgr-client to use API spec in new submodule ric-plt/e2mgr;
- removed cached copy
-* Silence many Sonar complaints
-* Revise license statements in documentation files
-* Revise stats screen to drop mock load, pendulum, reporting items
-
-Version 1.2.4, 24 Oct 2019
---------------------------
-* This version is used for the AT&T/Nokia co-create PIZ trials Nov 2019.
-* Revise a1-med-client to use API spec in new submodule ric-plt/a1;
- removed cached copy
-* Revise app manager client to use API spec in new submodule ric-plt/appmgr;
- removed cached copy
-* Add Platform page showing Kubernetes pods in aux and platform obtained from CAAS-Ingress
-* Update Angular libraries to recent stable versions
-* Revise user controller to answer data sent by portal, drop the mock implementation
-* Set global style for page titles
-* Align page titles to top left,decrease font size
-* Update EPSDK-FW to version 2.6
-* Make constructor robust to missing caasingress.insecure property
-* Repair bug that omitted slashes in CAAS-Ingress URL builder
-* Improve the dark mode
-* Show container ready count with total count
-
-Version 1.2.3, 4 Oct 2019
--------------------------
-* Serve unauthenticated user a login-at-portal page without using redirect
-* Upgrade to Spring-Boot 2.1.9.RELEASE
-
-Version 1.2.2, 27 Sep 2019
---------------------------
-* Support Portal security using EPSDK-FW cookie and user management
-
-Version 1.2.1, 20 Sep 2019
---------------------------
-* Repair E2 URLs in front end like endc-setup/endcSetup
-* Extend ANR mock feature to persist edits for demos
-* Block whitespace in E2 IP input field validation
-* Relax validation in E2 RAN name field validation
-* Make RAN connection table robust to missing fields
-* Install curl when building Docker image
-
-Version 1.2.0, 11 Sep 2019
---------------------------
-* Split URL properties into prefix/suffix parts
-* Add jacoco plugin to back-end for code coverage
-* Compile with Java version 11, use base openjdk:11-jre-slim
-* Clean code of issues reported by Sonar
-* Drop mock RAN names feature that supported R1 testing
-* Extend mock endpoints to simulate delay seen in tests
-* Move mock configuration classes into test area
-* Update App manager client to spec version 0.1.7
-* Add controller for page refresh of Angular routes
-* Extend E2 mock configuration for demo purposes
-* Add pattern for matching AC/admin application name
-* Add custom (plain but not white-label) error page
-* Synch A1 method paths in front-end and back-end
-* Add xapp dynamic configuration feature
-* Disable x-frame-options response header
-* Repair app manager undeploy-app back/front methods
-* Display AC xAPP metrics data via Kibana source (metrics.url.ac) on dashboard
-* Pass AC policy parameter without parsing as JSON
-* Use snake_case (not camelCase) names in AC policy front end
-* Update A1 mediator client to spec version 0.10.3
-* Extend AC control screen to read policy from A1
-* Create loading-dialog component and service
-* Showing the loading-dialog while making API call
-* Add notification and error handling for xapp configuration
-* Update E2 manager client to spec version 2.0.5 of 2019-09-11
-* Display MC xAPP metrics data via Kibana source (metrics.url.mc) on dashboard
-
-Version 1.0.5, 5 July 2019
---------------------------
-* Upgrade to Angular version 8
-* Upgrade to Spring-Boot 2.1.6.RELEASE
-* Align AC xApp policy page title
-* Update E2 manager client to spec version 20190703
-* Add configuration-driven mock of E2 getNodebIdList
-* Revise front-end components to use prefix 'rd'
-* Improve error handling in BE and FE code
-* Revise the notification service to display multiple notifications
-* Add JUnit test cases for controller methods
-
-Version 1.0.4, 27 June 2019
----------------------------
-* Add AC xApp neighbor control screen
-* Add ANR xApp neighbor cell relation table
-* Drop the pendulum xApp control screen
-* Add column sorting on xApp catalog, xApp control, ANR
-* Add disconnect-all button to RAN connection screen
-* Extend E2 service with disconnect-all method
-* Update ANR xApp client to spec version 0.0.8
-* Update E2 manager client to spec version 20190620
-* Adjust CSS and HTML for main container positioning
-* Revise config property keys to use URL (not basepath)
-* Left menu overlap main content fix
-* Extend back-end controllers to return error details
-* Add feature resilient to malformed instance data
-* Extend Xapp Controller with config endpoints
-* Add build number to dashboard version string
-* Move mock admin screen user data to backend
-* Update App manager client to spec version 0.1.5
-* Move RAN connection feature to control screen
-* Rework admin table
-* Update the notification service
-* Move RAN connection feature to control screen
-* Repair deploy-app feature and use icon instead of text button
-
-Version 1.0.3, 28 May 2019
---------------------------
-* Add AC xApp controller to backend
-* Add AC xApp interface to frontend
-* Add RAN type radio selector to connection setup
-* Update ANR xApp client to spec version 0.0.7
-* Update E2 manager client to spec version 20190515
-* Update xApp manager client to spec version 0.1.4
-* Add get-version methods to all controllers
-* Add simple page footer with copyright and version
-* Add AC and ANR xApp services
-* Rename signal service to E2 Manager service
-* Use XappMgrService to replace ControlService and CatalogService
-* Apply mat-table to control and catalog
-* RAN Connection screen upgrade to mat-table
-
-Version 1.0.2, 13 May 2019
---------------------------
-* Update A1 mediator client to version 0.4.0
-* Add E2 response message with timestamp and status code
-* Fetch xAPP instance status information from xAPP Manager and display in dashboard
-* Allow the user to initiate an E2 (X2) connection between RIC and gNB/eNB
-* User input validations on connections between RIC and eNB/gNB in the dashboard
-* Add ANR xApp backend with mock implementation
-* Add undeploy xApp function
-* Add shared confirm dialog
-* Add shared notification
-
-Version 1.0.1, 6 May 2019
--------------------------
-* Add draft A1 Mediator API definition
-* Use E2 Manager API definition dated 2 May 2019, with tag modifications
-* Adjust group IDs and packages for name O-RAN-SC; drop ORAN-OSC
-* Add ANR API spec and client code generator
-* Update xApp Manager API spec to version 0.1.2
-
-Version 1.0.0, 30 Apr 2019
---------------------------
-* Initial version
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index b13234a..6fc6e20 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -14,9 +14,9 @@
endpoint selection, is based on the message type rather than
on traditional DNS names or IP addresses. Because the user
documentation for RMR is a collection of UNIX manpages
-(included in the development package, and avalable via the
+(included in the development package, and available via the
man command when installed), there is no separate "User's
-Guide." To prvide something for the document scrapers to
+Guide." To provide something for the document scrapers to
find, this is a collection of the RMR manual pages formatted
directly from their source which might be a bit ragged when
combined into a single markup document. Read the manual pages
@@ -275,11 +275,11 @@
This is a convenience function as some wrapper languages
might not have the ability to directly copy into the payload
-buffer. The bytes from * src * for the length given are
-copied to the payload. It is the caller's responsibility to
-ensure that the payload is large enough. Upon successfully
-copy, the len field in the message buffer is updated to
-reflect the number of bytes copied.
+buffer. The bytes from *src* for the length given are copied
+to the payload. It is the caller's responsibility to ensure
+that the payload is large enough. Upon successfully copy, the
+len field in the message buffer is updated to reflect the
+number of bytes copied.
There is little error checking, and no error reporting.
@@ -691,18 +691,18 @@
The rmr_get_meid function will copy the managed equipment ID
(meid) field from the message into the *dest* buffer provided
-by the user. The buffer referenced by * dest * is assumed to
-be at least RMR_MAX_MEID bytes in length. If * dest * is
-NULL, then a buffer is allocated (the calling application is
+by the user. The buffer referenced by *dest* is assumed to be
+at least RMR_MAX_MEID bytes in length. If *dest* is NULL,
+then a buffer is allocated (the calling application is
expected to free when the buffer is no longer needed).
RETURN VALUE
--------------------------------------------------------------------------------------------
On success, a pointer to the extracted string is returned. If
-* dest * was supplied, then this is just a pointer to the
-caller's buffer. If * dest * was NULL, this is a pointer to
-the allocated buffer. If an error occurs, a nil pointer is
+*dest* was supplied, then this is just a pointer to the
+caller's buffer. If *dest* was NULL, this is a pointer to the
+allocated buffer. If an error occurs, a nil pointer is
returned and errno is set as described below.
ERRORS
@@ -722,7 +722,7 @@
ENOMEM
- A nil pointer was passed for * dest, * however it was not
+ A nil pointer was passed for *dest,* however it was not
possible to allocate a buffer using malloc().
@@ -1107,18 +1107,18 @@
The rmr_get_xact function will copy the transaction field
from the message into the *dest* buffer provided by the user.
-The buffer referenced by * dest * is assumed to be at least
-RMR_MAX_XID bytes in length. If * dest * is NULL, then a
-buffer is allocated (the calling application is expected to
-free when the buffer is no longer needed).
+The buffer referenced by *dest* is assumed to be at least
+RMR_MAX_XID bytes in length. If *dest* is NULL, then a buffer
+is allocated (the calling application is expected to free
+when the buffer is no longer needed).
RETURN VALUE
--------------------------------------------------------------------------------------------
On success, a pointer to the extracted string is returned. If
-* dest * was supplied, then this is just a pointer to the
-caller's buffer. If * dest * was NULL, this is a pointer to
-the allocated buffer. If an error occurs, a nil pointer is
+*dest* was supplied, then this is just a pointer to the
+caller's buffer. If *dest* was NULL, this is a pointer to the
+allocated buffer. If an error occurs, a nil pointer is
returned and errno is set as described below.
ERRORS
@@ -1138,7 +1138,7 @@
ENOMEM
- A nil pointer was passed for * dest, * however it was not
+ A nil pointer was passed for *dest,* however it was not
possible to allocate a buffer using malloc().
@@ -1186,7 +1186,7 @@
actual size of a specific message.
*Flags* allows for selection of some RMr options at the time
-of initialisation. These are set by ORing RMRFL_ constants
+of initialisation. These are set by ORing RMRFL constants
from the RMr header file. Currently the following flags are
supported:
@@ -1220,8 +1220,8 @@
adds the ability for a user application with multiple threads
to invoke a blocking call function with the guarentee that
the correct response message is delivered to the thread. The
-additional support is implemented with the * rmr_mt_call() *
-and * rmr_mt_rcv() * function calls.
+additional support is implemented with the *rmr_mt_call()*
+and *rmr_mt_rcv()* function calls.
Multi-threaded call support requires the user application to
specifically enable it when RMr is initialised. This is
@@ -1351,8 +1351,8 @@
--------------------------------------------------------------------------------------------
A value of 1 is returned on success, and 0 on failure. A
-failure indicates that the RMr context (void *) passed to
-this function was not valid.
+failure indicates that the RMr context (a void pointer passed
+to this function was not valid.
SEE ALSO
--------------------------------------------------------------------------------------------
@@ -1390,23 +1390,23 @@
user application supplies a completed message buffer, as it
would for a rmr_send_msg call, but unlike with a send, the
buffer returned will have the response from the application
-that received the message. The thread invoking the *
-rmr_mt_call()* will block until a message arrives or until
+that received the message. The thread invoking the
+*rmr_mt_call()* will block until a message arrives or until
*timeout* milliseconds has passed; which ever comes first.
Using a timeout value of zero (0) will cause the thread to
block without a timeout.
-The * id * supplied as the third parameter is an integer in
-the range of 2 through 255 inclusive. This is a caller
-defined "thread number" and is used to match the response
-message with the correct user application thread. If the ID
-value is not in the proper range, the attempt to make the
-call will fail.
+The *id* supplied as the third parameter is an integer in the
+range of 2 through 255 inclusive. This is a caller defined
+"thread number" and is used to match the response message
+with the correct user application thread. If the ID value is
+not in the proper range, the attempt to make the call will
+fail.
Messages which are received while waiting for the response
are queued on a *normal* receive queue and will be delivered
-to the user application with the next invocation of *
-rmr_mt_rcv() * or * rmr_rvv_msg().* by RMR, and are returned
+to the user application with the next invocation of
+*rmr_mt_rcv()* or *rmr_rvv_msg().* by RMR, and are returned
to the user application when rmr_rcv_msg is invoked. These
messages are returned in th order received, one per call to
rmr_rcv_msg.
@@ -1428,7 +1428,7 @@
message. (The application which returns the response message
is also expected to ensure that the return buffer has the
matching transaction ID. This can be done transparently if
-the application uses the * rmr_rts_msg() * function and does
+the application uses the *rmr_rts_msg()* function and does
not adjust the transaction ID.
Retries
@@ -1722,7 +1722,7 @@
RMR_ERR_NOTSUPP
The multi-threaded option was not enabled when RMr was
- initialised. See the man page for *rmr_init() * for
+ initialised. See the man page for *rmr_init()* for
details.
@@ -2467,8 +2467,8 @@
When the message cannot be successfully sent this function
will return the unsent (original) message buffer with the
-state set to indicate the reason for failure. The value of *
-errno * may also be set to reflect a more detailed failure
+state set to indicate the reason for failure. The value of
+*errno* may also be set to reflect a more detailed failure
reason if it is known.
In the event of extreme failure, a NULL pointer is returned.
@@ -2651,44 +2651,44 @@
The rmr_set_stimeout function sets the configuration for how
RMr will retry message send operations which complete with
-either a * timeout * or * again * completion value. (Send
+either a *timeout* or *again* completion value. (Send
operations include all of the possible message send
-functions: * rmr_send_msg(), rmr_call(), rmr_rts_msg() * and
-* rmr_wh_send_msg(). * The * rloops * parameter sets the
-maximum number of retry loops that will be attempted before
-giving up and returning the unsuccessful state to the user
-application. Each retry loop is approximately 1000 attempts,
-and RMr does ** not ** invoke any sleep function between
-retries in the loop; a small, 1 mu-sec, sleep is executed
-between loop sets if the * rloops * value is greater than 1.
+functions: *rmr_send_msg(), rmr_call(), rmr_rts_msg()* and
+*rmr_wh_send_msg().* The *rloops* parameter sets the maximum
+number of retry loops that will be attempted before giving up
+and returning the unsuccessful state to the user application.
+Each retry loop is approximately 1000 attempts, and RMr does
+**not** invoke any sleep function between retries in the
+loop; a small, 1 mu-sec, sleep is executed between loop sets
+if the *rloops* value is greater than 1.
Disabling Retries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default, the send operations will execute with an * rloop
-* setting of 1; each send operation will attempt to resend
-the message approximately 1000 times before giving up. If the
+By default, the send operations will execute with an *rloop*
+setting of 1; each send operation will attempt to resend the
+message approximately 1000 times before giving up. If the
user application does not want to have send operations retry
-when the underlying transport mechanism indicates * timeout *
-or * again, * the application should invoke this function and
-pass a value of 0 (zero) for * rloops. * With this setting,
-all RMr send operations will attempt a send operation only **
-once, ** returning immediately to the caller with the state
+when the underlying transport mechanism indicates *timeout*
+or *again,* the application should invoke this function and
+pass a value of 0 (zero) for *rloops.* With this setting, all
+RMr send operations will attempt a send operation only
+**once,** returning immediately to the caller with the state
of that single attempt.
RETURN VALUE
--------------------------------------------------------------------------------------------
-This function returns a -1 to indicate that the * rloops *
-value could not be set, and the value * RMR_OK * to indicate
+This function returns a -1 to indicate that the *rloops*
+value could not be set, and the value *RMR_OK* to indicate
success.
ERRORS
--------------------------------------------------------------------------------------------
-Currently errno is ** not ** set by this function; the only
-cause of a failure is an invalid context (* vctx *) pointer.
+Currently errno is **not** set by this function; the only
+cause of a failure is an invalid context (*vctx*) pointer.
EXAMPLE
--------------------------------------------------------------------------------------------
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..e8cc560
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,54 @@
+# vim: ts=4 expandtab sw=4:
+#==================================================================================
+# 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.
+#==================================================================================
+
+# This is needed only to support the RTD scraper(s)
+#
+# CAUTION: requires python/tox and maybe others to be installed in the dev environment
+# to test with:
+# tox -e docs
+#
+[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
+
