From 0596f6ac8433e4018cf328fa30fc09af020440b4 Mon Sep 17 00:00:00 2001
From: Erik Reid <erik.reid@geant.org>
Date: Sun, 24 Jan 2021 12:59:09 +0100
Subject: [PATCH] added configuratiom details

---
 docs/source/configuration.rst | 69 +++++++++++++++++++++++++++++++++++
 docs/source/index.rst         | 29 ++++++++++-----
 2 files changed, 88 insertions(+), 10 deletions(-)
 create mode 100644 docs/source/configuration.rst

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
new file mode 100644
index 00000000..3502d074
--- /dev/null
+++ b/docs/source/configuration.rst
@@ -0,0 +1,69 @@
+.. 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.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 836ac73f..a8524be3 100644
--- a/docs/source/index.rst
+++ b/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
-- 
GitLab