spread out docs

README.md

 # BRIAN Dashboard Manager
 
-## Overview
+The BRIAN Dashboard Manager is used
+provision Organizations and Dashboards in Grafana for BRIAN.
 
-This module is used to provision Organizations and Dashboards in Grafana for BRIAN.
-It implements a Flask-based webservice used only to trigger the provisioning process.
-
-The dashboards are generated from a list of interfaces obtained from Inventory Provider.
-
-Jinja templates are populated with data from these interfaces to render Dashboard JSON definitions sent to the Grafana API.
-
-Grafana API-related code lives in the `grafana` package.
-
-The `brian_dashboard_manager/grafana/provision.py` file is responsible for the entire provisioning lifecycle.
-
-Grafana API endpoints have wrapper functions in one file for relevant parts of the API, e.g. `brian_dashboard_manager/grafana/dashboard.py` for the dashboard API functions.
-
-Another example is `brian_dashboard_manager/grafana/organization.py` for the organization API functions.
-
-Some of the provisioned dashboards are not generated but are just static JSON files. These are put in the `brian_dashboard_manager/dashboards` directory. The same can be done for JSON datasource definitions in the `datasources` directory.
-
-The `brian_dashboard_manager/templating` package contains the code and Jinja templates used to render dashboard JSON. Most dashboards reuse the same templates, with the exception of NREN-specific dashboards, which has its own template.
-
-Of note is the `templating/helpers.py` file, which has all of the predicates and helper functions used to group interfaces together and generate the necessary data for the dashboard templates.
-The `templating/render.py` has functions for rendering of the various Jinja templates from the given data.
-
-## Configuration
-
-This app allows specification of a few
-example configuration parameters. These
-parameters should stored in a file formatted
-similarly to `config.json.example`, and the name
-of this file should be stored in the environment
-variable `CONFIG_FILENAME` when running the service.
-
-## Running this module
-
-This module has been tested in the following execution environments:
-
-- As an embedded Flask application.
-  For example, the application could be launched as follows:
+Documentation can be generated by running sphinx:
 
 ```bash
-$ export FLASK_APP=/path/to/brian_dashboard_manager/app.py
-$ export CONFIG_FILENAME=/path/to/config.json
-$ flask run
+sphinx-build -M html docs/source docs/build
 ```
 
-- As a `gunicorn` wsgi service.
-  - Details of `gunicorn` configuration can be found in the brian_dashboard_manager Puppet repository.
-
-## Protocol Specification
-
-The following resources can be requested from the webservice.
-
-### resources
-Any non-empty responses are JSON formatted messages.
-
-## /update
-
-This resource is used to trigger the provisioning to Grafana.
-It responds to the request immediately after starting the provisioning process.
-
-```json
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "message": {
-      "type": "string"
-    }
-  }
-}
-```
+The documents should be viewable in the
+workspace of the most recent [Jenkins job](https://jenkins.geant.org/job/brian-dashboard-manager/ws/docs/build/html/index.html).

brian_dashboard_manager/grafana/__init__.py

+"""
+Grafana module
+===============
+
+Grafana API-related code.
+
+Provisioning
+---------------
+.. automodule:: brian_dashboard_manager.grafana.provision
+
+
+Grafana API
+-------------
+.. automodule:: brian_dashboard_manager.grafana.dashboard
+
+
+Organizations
+----------------
+.. automodule:: brian_dashboard_manager.grafana.organization
+
+
+
+"""
\ No newline at end of file

brian_dashboard_manager/grafana/dashboard.py

+"""
+Grafana Dashhboard API endpoints wrapper functions.
+"""
 import logging
 import os
 import json

brian_dashboard_manager/grafana/organization.py

+"""
+Grafana Organization management helpers.
+
+"""
 import random
 import string
 import logging

brian_dashboard_manager/grafana/provision.py

+"""
+This module is responsible for the
+entire provisioning lifecycle.
+"""
 import logging
 import time
 from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor

brian_dashboard_manager/routes/update.py

@@ -6,6 +6,16 @@ from brian_dashboard_manager import CONFIG_KEY
 
 routes = Blueprint("update", __name__)
 
+UPDATE_RESPONSE_SCHEMA = {
+    '$schema': 'http://json-schema.org/draft-07/schema#',
+    'type': 'object',
+    'properties': {
+        'message': {
+            'type': 'string'
+        }
+    }
+}
+
 
 @routes.after_request
 def after_request(resp):
@@ -14,6 +24,19 @@ def after_request(resp):
 
 @routes.route('/', methods=['GET'])
 def update():
+    """
+    This resource is used to trigger the provisioning to Grafana.
+
+    It responds to the request immediately after starting the provisioning process.
+
+
+    The response will be formatted according to the following schema:
+
+    .. asjson::
+       brian_dashboard_manager.routes.update.UPDATE_RESPONSE_SCHEMA
+
+    :return: json
+    """
     executor = ThreadPoolExecutor(max_workers=1)
     executor.submit(provision, current_app.config[CONFIG_KEY])
     return {'data': {'message': 'Provisioning dashboards!'}}

brian_dashboard_manager/templating/__init__.py

+"""
+Code and
+Jinja templates used to render dashboard JSON.
+Most dashboards reuse the
+same templates, with the exception of
+NREN-specific dashboards, which has
+its own template.
+
+
+Templates
+-----------
+Some of the provisioned dashboards are not generated but are just static
+JSON files. These are put in the `brian_dashboard_manager/dashboards` directory.
+The same can be done for JSON datasource definitions in the `datasources` directory.
+
+
+Helpers
+---------
+.. automodule:: brian_dashboard_manager.templating.helpers
+
+
+Rendering
+---------
+.. automodule:: brian_dashboard_manager.templating.render
+
+"""

brian_dashboard_manager/templating/helpers.py

+"""
+Predicates
+and helper functions used to group interfaces together and generate the
+necessary data for the dashboard templates.
+"""
 import re
 import logging
 import json

brian_dashboard_manager/templating/render.py

+"""
+Methods for rendering of the
+various Jinja templates from the given data.
+"""
 import os
 import json
 import jinja2

docs/source/configuration.rst

+
+Configuration and Running
+=========================
+
+Configuration
+-------------
+
+This app allows specification of a few
+example configuration parameters. These
+parameters should stored in a file formatted
+similarly to `config.json.example`, and the name
+of this file should be stored in the environment
+variable `CONFIG_FILENAME` when running the service.
+
+Running this module
+---------------------
+
+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:: python
+
+   export FLASK_APP=/path/to/brian_dashboard_manager/app.py
+   export CONFIG_FILENAME=/path/to/config.json
+   flask run
+
+* As a `gunicorn` wsgi service.
+
+  * Details of `gunicorn` configuration can be found in the
+    brian_dashboard_manager Puppet repository.
\ No newline at end of file

docs/source/index.rst

@@ -3,18 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to BRIAN Dashboard Manager's documentation!
-===================================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+Inventory Provider
+==================
 
+The BRIAN Dashboard Manager is used
+provision Organizations and Dashboards in Grafana for BRIAN.
 
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   configuration
+   overview
+   protocol

docs/source/overview.rst

+
+Overview
+=========================
+
+This module is used to provision Organizations and Dashboards inGrafana for BRIAN.
+
+The dashboards are generated from a list of interfaces obtained from Inventory Provider.
+
+Jinja templates are populated with data from these interfaces to render
+Dashboard JSON definitions sent to the Grafana API.
+
+.. automodule:: brian_dashboard_manager.grafana
+
+.. automodule:: brian_dashboard_manager.templating

docs/source/protocol.rst

+
+Protocol
+=========================
+
+
+This module implements a Flask-based webservice used only to
+trigger the provisioning process.
+
+The following resources can be requested from the webservice.
+
+resources
+-----------
+Any non-empty responses are JSON formatted messages.
+
+
+/update
+*********
+
+.. autofunction::  brian_dashboard_manager.routes.update.update