Documentation changes needed to support RTD
Changes which are necessary to support a docs directory that
is scraped for "read the docs." Changes include:
Tweaks to manual pages to allow them to be combined into a
large "user's guide" (removed the final quit command).
Addition of an rtd subidrectory under source and the needed
.xfm source to generate the various .rst files in the top
level docs (plural).
Moved the top level readme to the main source directory as
it was out of place at the top; created a new top level README.
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: I708a750e3c58df4d0446eb3a5706c10bf65bed1d
diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
new file mode 100644
index 0000000..151a6f4
--- /dev/null
+++ b/docs/developer-guide.rst
@@ -0,0 +1,98 @@
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+
+RMR Developer Guide
+============================================================================================
+
+The RIC Message Router (RMR) is a library which applications
+use to send and receive messages where the message routing,
+endpoint selection, is based on the message type rather than
+on traditional DNS names or IP addresses. This document
+contains information that potential developers might need to
+know in order to contribute to the project
+
+Language
+--------------------------------------------------------------------------------------------
+
+RMR is written in C, and thus a contributing developer to the
+core library should have an excellent working knowledge of C.
+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.
+
+Code Structure
+--------------------------------------------------------------------------------------------
+
+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
+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
+the library generated for use with the NNG transport.
+
+As such the library source is organised into multiple
+components:
+
+
+common
+
+ Source in the common directory is agnostic to the
+ underlying transport mechanism (Nanomsg or NNG), and thus
+ can be used when generating either library.
+
+nano
+
+ Source which is tightly coupled with the underlying
+ Nanomsg library. (Nanomsg has been dreprecated, but the
+ RMR source remains as an example.)
+
+nng
+
+ Source which is tightly coupled with the underlying NNG
+ library.
+
+
+
+Internal Function Exposure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The decision to limit as much as practical the exposure of
+truely interal 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.
+
+Coding Style
+--------------------------------------------------------------------------------------------
+
+There is a list of coding style guidelines in the top level
+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,
+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
+the creator of a module.
+
+Building
+--------------------------------------------------------------------------------------------
+
+RMR is constructed using CMake. While CMake's project
+description can be more cumbersome than most typical
+Makefiles, the tool provides convenience especially when it
+comes to creating packages.