Documentation update

documentation/source/building.rst

@@ -25,7 +25,7 @@ Dripline build options include:
       if ON, builds the example applications
 
    ``Dripline_BUILD_PYTHON`` (BOOL)
-      if ON, builds utilities used by the Python wrapping
+      if ON, builds utilities used by the Python wrapping (Dripline python wrapping is done in Dripline-python)
 
    ``Dripline_ENABLE_EXECUTABLES`` (BOOL)
       if ON, builds the Dripline executables
@@ -52,22 +52,15 @@ The CMake option and possible values are:
       ``Release``
          only prints warning and error messages; highly optimized, and no debugging symbols included
 
-You can additionally define preprocessor macros that are used directly in the code:
-
-.. glossary::
-
-   ``DRIPLINE_AUTH_FILE`` (PATH)
-      specifies the location and filename of the default authentication file
-
-
 .. _standalone-option:
 
 Standalone Option
 =================
 
 In standalone mode, one compiles only the dripline-cpp repository and its dependencies.
-This option is best for testing, providing access to commandline tools, or when a derrived software product uses dripline-cpp as an external dependency.
+This option is best for testing, providing access to command-line tools, or when a derrived software product uses dripline-cpp as an external dependency.
 This is the approach used in the Dockerfile, which is included in the dripline-cpp repository and used to automatically build dripline-cpp container images.
+Dripline-python's recommended build also expects dripline-cpp as an external dependency.
 The steps are:
 
 1. Clone the repository::
@@ -96,7 +89,6 @@ Submodule Option
 
 The submodule build configuration is for when the dripline-cpp is being include as a git submodule in some derived package's repository.
 This option is best when you want to track and pin the exact dripline-cpp version to be used in another project and you want to build them together using cmake.
-This is the approach used in the dripline-python package, which builds a python library on top of dripline-cpp.
 The steps for this mode are:
 
 1. Go to the top-level directory of the parent pacakge in which you want to include dripline-cpp::

documentation/source/configuration.rst

@@ -4,6 +4,11 @@ Configuration
 
 An application that uses the Scarab application framework, including ``dl-agent`` and ``dl-mon``, 
 will have a global dictionary-like set of configuration parameters.  
+The parameters can generally be divided into two sets:
+
+    1. Dripline-mesh parameters, which describe the specifications of the mesh that is being used, and 
+    2. Application parameters, which are particular to the application being run (e.g. ``dl-agent`` or a service)
+
 In this documentation, configurations will be indicated using YAML, and the mapping collection.  
 In the source code, this is implemented as a ``scarab::param_node``. 
 
@@ -43,7 +48,7 @@ The defaults for all of these parameters are given in the class ``dripline_confi
 
 .. code-block:: YAML
 
-    dripline:
+    dripline_mesh:
         broker: localhost
         broker_port: 5672
         requests_exchange: requests
@@ -226,3 +231,28 @@ Here's an example configuration, shown in YAML format, where environment variabl
 
 In this case the user wants a customized broker address specified at runtime by the contents of the ``DL_PREFIX`` 
 environment variable, and they want to specify the port with ``DL_PORT``.
+
+Recommended Setup
+=================
+
+The above sections describe many ways in which Dripline applications can be configured.  
+For convenience to the user and ease of maintenance, we recommend the following setup:
+
+    1. Provide the default mesh information in a ``.dripline_mesh.yaml`` file in the user's home directory.  
+    At a minimum, include the broker address in that file.
+    2. For authentication information:
+
+        A. For manual interactive use (e.g. using ``dl-agent``), supply the RabbitMQ login details, and 
+        the login details for any other applications (e.g. database) with environment variables.
+
+        B. For deployed use (e.g. Docker Swarm or Kubernetes running services) either use environment variables 
+        or secrets files.
+
+Examples
+========
+
+The dripline-cpp integration tests provide a variety of examples of how to configure dripline-cpp applications.  
+These are found in the source directory ``testing/integration``.  
+You'll find several services started in different ways in ``docker-compose.yaml``, 
+and a number of ``dl-agent`` commands configured differently in ``dl-tests.sh``.
+

documentation/source/getting_started.rst

@@ -13,10 +13,13 @@ What's Included
 Requirements
 ============
 
-* CMake 3.1
-* C++11
+* CMake 3.12
+* C++17
 * Boost 1.46
 * rabbitmqc
+* libyaml-cpp
+* rapidjson
+* quill (logging library)
 
 
 Included Packages
@@ -26,10 +29,10 @@ Included Packages
 * `scarab <https://github.com/project8/scarab>`_
 
 
-Getting Dripline-cpp
+Getting dripline-cpp
 ====================
 
-The Dripline-cpp repository is available on `GitHub <https://driplineorg.github.com/dripline-cpp>`_.
+The dripline-cpp repository is available on `GitHub <https://driplineorg.github.com/dripline-cpp>`_.
 
 Dripline-cpp can either be built manually, or used from a Docker container.
 
@@ -42,7 +45,7 @@ Images are automatically built for each tagged release, and for the ``main`` and
 Users can also build their own images using the provided Dockerfile or by customizing their own.
 
 
-Using Dripline-cpp
+Using dripline-cpp
 ================== 
 
 See :ref:`Agent <dl-agent>` and :ref:`Monitor <dl-mon>` for instructions on using the included applications.
@@ -54,4 +57,5 @@ Setting Up a Mesh
 =================
 
 Instructions and examples for setting up a dripline mesh can be found 
-from the main `dripline documentation site <https://driplineorg.github.io>`_.
+from the main `dripline documentation site <https://driplineorg.github.io>`_ 
+and in the dripline-cpp integration tests.

documentation/source/index.rst

@@ -23,7 +23,6 @@ Contents:
    Monitor <dl_mon>
    Library <library>
    Configuration <configuration>
-   Authentication <authentication>
    Offline & No-Connection <offline>
 
 .. end of toc

documentation/source/library.rst

@@ -71,6 +71,8 @@ The interface for running a service consists of three functions:
 * ``listen()`` (blocking)
 * ``stop()``
 
+Or you can use ``run()`` to perform the start-->listen-->stop sequence.
+
 A service can have both synchronous and asynchronous child endpoints.  With the former, requests are 
 handled synchronously with the recieving of messages and with processing messages bound for itself.  
 With the latter, requests are passed to the appropriate endpoint, which handles them in its own thread.