added configuratiom details

docs/source/configuration.rst

+.. notes and hints about confiuguration and running
+
+Configuration and Running
+=========================
+
+Configuration
+-------------
+
+The module requires two configuration files to be provided
+when launching the web service.
+
+The first configuration file
+must be stored in the environment variable
+`SETTINGS_FILENAME` and is parsed as a Flask configuration
+file.  The file is python and there are two
+custom variables, and adding other Flask-specific
+options is not supported and has not been tested.
+
+* `INVENTORY_PROVIDER_CONFIG_FILENAME`
+
+  * [REQUIRED] Run-time accessible filename
+    of a json file containing the server configuration parameters.  This file
+    must be formatted according to the following json schema
+
+* ENABLE_TESTING_ROUTES
+
+  * [OPTIONAL, default value: False]
+    Boolean flag (can be any value that evaluates to True)
+    to enable routes to special utilities used for testing.
+    *This must never be enabled in a production environment.*
+
+The following is an example of a configuration file.
+
+.. code-block:: python
+
+   INVENTORY_PROVIDER_CONFIG_FILENAME = "/somepath/config.json"
+   ENABLE_TESTING_ROUTES = True
+
+
+The second required file contains Inventory Provider application-level
+configuration parameters.
+
+.. autofunction:: inventory_provider.config.load
+
+
+Running
+--------
+
+This module has been tested in the following execution environments:
+
+* As an embedded Flask application.
+  For example, the application could be launched as follows:
+
+  .. code-block:: bash
+
+     $ export FLASK_APP=app.py
+     $ export SETTINGS_FILENAME=settings.cfg
+     $ flask run
+
+* As an Apache/`mod_wsgi` service.
+
+  * Details of Apache and `mod_wsgi`
+    configuration are beyond the scope of this document.
+
+* As a `gunicorn` wsgi service.
+
+  * Details of `gunicorn` configuration are
+    beyond the scope of this document.
+

docs/source/index.rst

@@ -3,18 +3,27 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Inventory Provider's documentation!
-==============================================
+Inventory Provider
+==================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+Documentation for Inventory Provider.
+This service acts as a single point of truth for
+information about the GÉANT network, exposed by
+a Flask-based web service.
 
+The webservice communicates with clients over HTTP.
+Responses to valid requests are returned as JSON messages.
+The server will therefore return an error unless
+`application/json` is in the `Accept` request header field.
 
+HTTP communication and JSON grammar details are
+beyond the scope of this document.
+Please refer to [RFC 2616](https://tools.ietf.org/html/rfc2616)
+and www.json.org for more details.
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   configuration