From 9846c5d73f062217e7669f44808200eed7ff1dae Mon Sep 17 00:00:00 2001
From: Erik Reid <erik.reid@geant.org>
Date: Tue, 16 Mar 2021 15:33:43 +0100
Subject: [PATCH] spread out docs
---
README.md | 73 ++-----------------
brian_dashboard_manager/grafana/__init__.py | 23 ++++++
brian_dashboard_manager/grafana/dashboard.py | 3 +
.../grafana/organization.py | 4 +
brian_dashboard_manager/grafana/provision.py | 4 +
brian_dashboard_manager/routes/update.py | 23 ++++++
.../templating/__init__.py | 26 +++++++
brian_dashboard_manager/templating/helpers.py | 5 ++
brian_dashboard_manager/templating/render.py | 4 +
docs/source/configuration.rst | 32 ++++++++
docs/source/index.rst | 20 ++---
docs/source/overview.rst | 14 ++++
docs/source/protocol.rst | 19 +++++
13 files changed, 173 insertions(+), 77 deletions(-)
create mode 100644 docs/source/configuration.rst
create mode 100644 docs/source/overview.rst
create mode 100644 docs/source/protocol.rst
diff --git a/README.md b/README.md
index 84a65db..6479408 100644
--- a/README.md
+++ b/README.md
@@ -1,74 +1,13 @@
# 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).
diff --git a/brian_dashboard_manager/grafana/__init__.py b/brian_dashboard_manager/grafana/__init__.py
index e69de29..2857b60 100644
--- a/brian_dashboard_manager/grafana/__init__.py
+++ b/brian_dashboard_manager/grafana/__init__.py
@@ -0,0 +1,23 @@
+"""
+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
diff --git a/brian_dashboard_manager/grafana/dashboard.py b/brian_dashboard_manager/grafana/dashboard.py
index 19c1fee..7763af5 100644
--- a/brian_dashboard_manager/grafana/dashboard.py
+++ b/brian_dashboard_manager/grafana/dashboard.py
@@ -1,3 +1,6 @@
+"""
+Grafana Dashhboard API endpoints wrapper functions.
+"""
import logging
import os
import json
diff --git a/brian_dashboard_manager/grafana/organization.py b/brian_dashboard_manager/grafana/organization.py
index 4c01096..d075660 100644
--- a/brian_dashboard_manager/grafana/organization.py
+++ b/brian_dashboard_manager/grafana/organization.py
@@ -1,3 +1,7 @@
+"""
+Grafana Organization management helpers.
+
+"""
import random
import string
import logging
diff --git a/brian_dashboard_manager/grafana/provision.py b/brian_dashboard_manager/grafana/provision.py
index 90eae88..bdb0e29 100644
--- a/brian_dashboard_manager/grafana/provision.py
+++ b/brian_dashboard_manager/grafana/provision.py
@@ -1,3 +1,7 @@
+"""
+This module is responsible for the
+entire provisioning lifecycle.
+"""
import logging
import time
from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
diff --git a/brian_dashboard_manager/routes/update.py b/brian_dashboard_manager/routes/update.py
index 681c867..c5d8390 100644
--- a/brian_dashboard_manager/routes/update.py
+++ b/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!'}}
diff --git a/brian_dashboard_manager/templating/__init__.py b/brian_dashboard_manager/templating/__init__.py
index e69de29..b13a000 100644
--- a/brian_dashboard_manager/templating/__init__.py
+++ b/brian_dashboard_manager/templating/__init__.py
@@ -0,0 +1,26 @@
+"""
+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
+
+"""
diff --git a/brian_dashboard_manager/templating/helpers.py b/brian_dashboard_manager/templating/helpers.py
index 1171c9f..fea1a1f 100644
--- a/brian_dashboard_manager/templating/helpers.py
+++ b/brian_dashboard_manager/templating/helpers.py
@@ -1,3 +1,8 @@
+"""
+Predicates
+and helper functions used to group interfaces together and generate the
+necessary data for the dashboard templates.
+"""
import re
import logging
import json
diff --git a/brian_dashboard_manager/templating/render.py b/brian_dashboard_manager/templating/render.py
index dede30c..2aa06bf 100644
--- a/brian_dashboard_manager/templating/render.py
+++ b/brian_dashboard_manager/templating/render.py
@@ -1,3 +1,7 @@
+"""
+Methods for rendering of the
+various Jinja templates from the given data.
+"""
import os
import json
import jinja2
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
new file mode 100644
index 0000000..5f35ebc
--- /dev/null
+++ b/docs/source/configuration.rst
@@ -0,0 +1,32 @@
+
+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
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6e0e3cd..97444a5 100644
--- a/docs/source/index.rst
+++ b/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
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
new file mode 100644
index 0000000..063ba7e
--- /dev/null
+++ b/docs/source/overview.rst
@@ -0,0 +1,14 @@
+
+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
diff --git a/docs/source/protocol.rst b/docs/source/protocol.rst
new file mode 100644
index 0000000..bb1ebfd
--- /dev/null
+++ b/docs/source/protocol.rst
@@ -0,0 +1,19 @@
+
+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
--
GitLab