Merge pull request #5 from jkittley/dev

Documentation refactoring and better Purge tools
jkittley · Mar 21, 2018 · c40ffdc · c40ffdc
2 parents 78b1cae + 389b8dc
commit c40ffdc
Show file tree

Hide file tree

Showing 32 changed files with 745 additions and 219 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,11 +1,12 @@
 
 old/
 *.pyc
-server/config/secure.py
 server/data/tinydb/*.json
 server/data/*.db
 backups/
 docs/build/
 docs/make.bat
 docs/Makefile
-*.afdesign
+*.afdesign
+server/test/.pytest_cache/
+server/.pytest_cache/
diff --git a/docs/img/logo.png b/docs/img/logo.png
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,7 +1,8 @@
 .. include:: global.rst
 
-API Documentation
-=================
+RESTful API Documentation
+=========================
+This section documents the RESTful API offered by |project|. Using the URI endpoints listed below you can add and examine data collected by sensor devices on your network.
 
 Summary
 -------

diff --git a/docs/source/api/utils.Device.rst b/docs/source/api/utils.Device.rst
@@ -12,8 +12,10 @@ Device
 
       ~Device.add_reading
       ~Device.as_dict
+      ~Device.count
       ~Device.fields
       ~Device.get_commlinks
+      ~Device.get_dtypes
       ~Device.get_readings
       ~Device.is_registered
       ~Device.last_reading
@@ -23,8 +25,10 @@ Device
 
    .. automethod:: add_reading
    .. automethod:: as_dict
+   .. automethod:: count
    .. automethod:: fields
    .. automethod:: get_commlinks
+   .. automethod:: get_dtypes
    .. automethod:: get_readings
    .. automethod:: is_registered
    .. automethod:: last_reading

diff --git a/docs/source/api/utils.Logger.rst b/docs/source/api/utils.Logger.rst
@@ -16,7 +16,6 @@ Logger
       ~Logger.error
       ~Logger.funcexec
       ~Logger.get_categories
-      ~Logger.get_ifdb
       ~Logger.interaction
       ~Logger.list_records
       ~Logger.purge
@@ -30,7 +29,6 @@ Logger
    .. automethod:: error
    .. automethod:: funcexec
    .. automethod:: get_categories
-   .. automethod:: get_ifdb
    .. automethod:: interaction
    .. automethod:: list_records
    .. automethod:: purge

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -138,24 +138,27 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'logo_only': True,
+    'collapse_navigation': False
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = 'sensortank v0.0'
+# html_title = 'Little Sense v0.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
-# html_short_title = None
+html_short_title = ""
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
-# html_logo = None
+html_logo = "../img/logo.png"
 
 # The name of an image file (relative to this directory) to use as a favicon of
 # the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

diff --git a/docs/source/custom_commlinks.rst b/docs/source/custom_commlinks.rst
@@ -2,4 +2,4 @@
 
 Adding Radios
 =============
-Coming soon
+Radios / communication links are in the most part is very straight forward to install and configure. However, each technology has its own set of dependancies and installation quirks. Rather than detail everything here, we refer you to the readme file assosiated with each radio. Details can be found in the `commlinks directory <https://github.com/jkittley/LittleSense/tree/master/server/commlink>`_. 
diff --git a/docs/source/custom_dashboards.rst b/docs/source/custom_dashboards.rst
@@ -1,5 +1,179 @@
 .. include:: global.rst
 
-Add/Edit Dashboards
-===================
-Coming soon
+Dashboards
+==========
+Dashboards are just a collections of plots and can be defined in a Dashboard JSON files. These files can be found in the ```data/dashboards``` directory. |project| automatically scans this folder and adds new dashboards to the menu. Below we dicuss how dashboard files are constructed.
+
+At the top level dashboards have 3 sections: A *header*, a *footer* and an array of *plots*. The header and footer can either be "null" as per the footer in the example below, or it can be an object with a title and text attribute, see header in example. 
+
+.. code::
+
+    {
+        "header": {
+            "title": "Some title",
+            "text": "Some descriptive text"
+        },
+        "footer": null,
+        "plots": [ "-- See below --" ]
+    }
+
+.. warning:: JSON does not like trailing commas (unlike Python) and is very strict! Curious Concept have a nice `validation tool <https://jsonformatter.curiousconcept.com/>`_ which will happlily point out all your mistakes.
+
+Plots
+-----
+Each item in the plots array must be an object like the one in the example below.
+
+.. code:: 
+
+    "plots": [
+        {
+            "id": 1,
+            "pos": 1,
+            "title": "Plot 1",
+            "width": 6,
+            "help": "Some help text for the viewer",
+            "metrics": [ '-- See below --' ],
+            "time": {},
+            "type": "timeseries",
+            "refresh_interval_seconds": 5
+        },
+        ...
+    ]
+
+:id: Must be unique.
+:pos: Used to order the plots. Starts in the top left.
+:title: The plot title
+:width: The plot width. A vaulue from 1 to 12
+:help: Help text for the user
+:metrics: See below
+:time: See below
+:type: The type of plot. Must be one of the following: "timeseries", more soon.
+:refresh_interval_seconds: Number of seconds between each refresh of the plot. Can be set to null to disable automatic refresh.
+
+Time
+----
+The time attribute must be an object and be structured as follows:
+
+.. code:: 
+
+    "time": {
+        "start": null,
+        "end": null,
+        "reading_interval_seconds": 10,
+        "period": {
+            "days": 0,
+            "hours": 0,
+            "minutes": 5
+        },
+        "fill": "none"
+    }
+
+:start: The start of the time period to be displayed. If null the default will be the end minus the period.
+:end: The end of the time period to be displayed. If null then the current time is used and will auto update to the current time each refresh. 
+:reading_interval_seconds: Group readings into intervals of this many seconds.
+:period: A period of time messured in days, hours and minutes. If start and end are set this is ignored. 
+:fill: If "none" then reading_intervals which contain no readings will be skipped. If "null" then reading_intervals with no readings return a null value.
+
+Metrics
+-------
+Metrics represent the data to be displayed and how to present it.
+
+.. code::
+
+    "metrics": [
+        {
+            "name": "Device 1: Signal (dB)",
+            "field_id": "float_signal_db",
+            "device_id": "test_device_1",
+            "aggrfunc": "mean"             
+        },
+        ...
+    ]
+
+:name: A friendly name for the user to read
+:field_id: The id of the field to be displayed
+:device_id: The device from which the field should be obtained
+:aggrfunc: The method of aggregating readings when grouped by intervals. The values should be set to one of the following depending on the data type of the field.
+
+    - Numeric: 'count', 'mean', 'mode', 'median', 'sum', 'max', 'min', 'first' or 'last'. 
+    - Booleans: 'count', 'first' or 'last' and 
+    - Strings: 'count', 'first' or 'last'.
+
+Full example
+------------
+
+.. code-block:: json
+
+    {
+        "header": null,
+        "footer": null,
+        "plots": [
+            {
+                "id": 1,
+                "pos": 1,
+                "title": "Plot 1",
+                "width": 6,
+                "help": "Some help text for the viewer",
+                "metrics": [{
+                    "name": "Device 1: Signal (dB)",
+                    "field_id": "float_signal_db",
+                    "device_id": "test_device_1",
+                    "aggrfunc": "mean"             
+                },{
+                    "name": "Device 1: Max Light Level (Lux)",
+                    "field_id": "int_light_level_lux",
+                    "device_id": "test_device_1",
+                    "aggrfunc": "max"
+                },{
+                    "name": "Device 2: Switch State (OnOff)",
+                    "field_id": "bool_switch_state",
+                    "device_id": "test_device_2",
+                    "aggrfunc": "count"
+                }],
+                "time": {
+                    "start": null,
+                    "end": null,
+                    "reading_interval_seconds": 10,
+                    "period": {
+                        "days": 0,
+                        "hours": 0,
+                        "minutes": 5
+                    },
+                    "fill": "none"
+                },
+                "type": "timeseries",
+                "refresh_interval_seconds": 5
+            },
+            {
+                "id": 2,
+                "pos": 2,
+                "title": "Plot 2",
+                "width": 6,
+                "help": "Some help text for the viewer",
+                "metrics": [{
+                    "name": "Device 2: Temp (C)",
+                    "field_id": "float_temp_c",
+                    "device_id": "test_device_2",
+                    "agrfunc": "mean"             
+                },{
+                    "name": "Device 2: Switch State (OnOff)",
+                    "field_id": "bool_switch_state",
+                    "device_id": "test_device_2",
+                    "aggrfunc": "count"
+                }],
+                "time": {
+                    "start": null,
+                    "end": null,
+                    "reading_interval_seconds": 5,
+                    "period": {
+                        "days": 0,
+                        "hours": 0,
+                        "minutes": 5
+                    },
+                    "fill": "none"
+                },
+                "type": "timeseries",
+                "refresh_interval_seconds": 5
+            }
+            ]
+    }
diff --git a/docs/source/custom_logo.rst b/docs/source/custom_logo.rst
diff --git a/docs/source/custom_look.rst b/docs/source/custom_look.rst
@@ -0,0 +1,12 @@
+.. include:: global.rst
+
+Change the look and feel
+========================
+Making |project| your own couldn't be easier. There are a few things you need to know before you get started.
+
+1. ```static/img/``` holds all the images.
+2. ```templates/``` is where all the HTML, CSS and Javascript lives. The CSS and Javascript needed by each is either included in the template itself or in its parent. For experienced programmers this may appear as we have gone mad, but we chose to structure things this was so it is really obvious to novices what effects what.
+3. ```templates/base.html``` is extended by all other templates. For more information about how to manipulate the templates see http://flask.pocoo.org/docs/templating/.
+
+
+
diff --git a/docs/source/customisation.rst b/docs/source/customisation.rst
@@ -2,14 +2,13 @@
 
 Customising |project|
 =====================
-Yay, you are all setup and want to make |project| your own. On this page we link to tutorials which will guide you through making changes to |project|.
-
-What do you want to change?
----------------------------
+Now you are all setup, you can make |project| your own by adding a little style. 
 
 .. toctree::
    :maxdepth: 1
 
-   custom_logo
+   custom_look
    custom_dashboards
-   custom_commlinks
+   custom_commlinks
+   utils
+   exceptions
diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst
@@ -2,7 +2,7 @@
 
 Exceptions (utils.exceptions)
 =============================
-In addtion the utils.exceptions module contains a number of bespoke exceptions.
+The utils.exceptions module contains a number of bespoke exceptions. These were implemented just to make the reasons for failure more obvious.
 
 .. automodapi:: utils.exceptions
   :no-heading:

diff --git a/docs/source/getdata.rst b/docs/source/getdata.rst
@@ -0,0 +1,16 @@
+.. include:: global.rst
+
+Getting Data
+============
+Now you have a |project| Raspberry Pi server up and running we need to start collecting some data. You can begin by generating some test data (see receiving data for more details).
+
+.. toctree::
+   :maxdepth: 1
+
+   receive
+   device
+
+
+
+
+
diff --git a/docs/source/getstarted.rst b/docs/source/getstarted.rst
@@ -0,0 +1,24 @@
+.. include:: global.rst
+
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   server_install
+   server_extra
+
+Video Overview
+^^^^^^^^^^^^^^
+
+This is a 10 minute video which walks you through the setup process from installing NOOBs on your Pi to having the server ready to collect data. 
+
+.. raw:: html
+
+    <iframe width="690" height="380" src="https://www.youtube.com/embed/gAPfL7tdLxY" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+    <br>
+    <br>
+
+
+