Jonny finished with docs (#139)

whup whup

-    narrative documentation for software overview, all gui modules, all alarm modules, common.values , common.message (except for stuff manuel needs ta do), common.loggers (except for stuff manuel needs to do), common.prefs, common.unit_conversion
-    API documentation, docstrings for every method, user-facing attribute, function and constant in all the above. Only exception is gui.widgets.components which are p self explanatory
-    Figures for software overview, gui overview, gui screenshot
-    cleaned up dead/obsolete code with no uses in all the above


* common module overview

* testing module-level docstrings

* Docstrings for values.py

* splitting alarm into multiple files

* basic description of alarms

* actually adding to toctree

* test syntax highlighting?

* broken toctree

* finding the right objects maybe?

* continuing alarm docs
removing persistent alarm rule attribute

* moving example to alarm rule page

adding docstring to alarm definition

* toc in the main page

* breaking into list

* correct titles in alarm toc

* link to alarm rule source

* spacing in list

* alarm manager documentation

* test inheritance diagram

alarm object documentation, condition documentation

* condition documentation

* importing correctly

* add link to raw alarm definitions

* prefs documentation

* messages docs

* put prefs below header so lists render right???

* test order of class and init docstrings

* loggers documentation
removing old log_exception function

* unit conversions docs

* alarm bar documentation

* class style

* source link color

* control panel docs

* display docs

* plot docs

* statement on components

* wrapped supposed to raise exceptions my b

_docs/_src/sass/_theme_etc_local.sass

@@ -60,3 +60,13 @@
 //make methods a lil more distinguishable
 .method
   border-top: 1px dotted $gray
+
+//Make classes stand out a bit better
+.class
+  border-top: 1px solid $accent-color
+  padding-top: 1rem
+  margin-top: 3rem
+
+  >dt:first-child
+    margin-bottom: 2rem
+    font-size: 125%

_docs/_src/sass/_theme_variables.sass

@@ -27,7 +27,7 @@ $link-color-hover:                    lighten($link-color, 6%) !default
 $link-color-alt:                      hsl(33, 100%, 51%)
 
 // Code colors
-$text-viewcode-color:                 $green
+$text-viewcode-color:                 $accent-color
 $text-codexref-color:                 $text-color
 
 // Definition list colors

_docs/alarm.alarm.rst

@@ -0,0 +1,11 @@
+Alarm Objects
+================
+
+Alarm objects represent the state and severity of active alarms, but are otherwise intentionally quite featureless.
+
+They are created and maintained by the :class:`.Alarm_Manager` and sent to any listeners registered in :class:`.Alarm_Manager.callbacks` .
+
+.. automodule:: pvp.alarm.alarm
+    :members:
+    :undoc-members:
+    :autosummary:

_docs/alarm.alarm_manager.rst

@@ -0,0 +1,15 @@
+Alarm Manager
+================
+
+The alarm manager is responsible for checking the :class:`.Alarm_Rule` s and maintaining
+the :class:`.Alarm` s active in the system.
+
+Only one instance of the :class:`.Alarm_Manager` can be created at once, and if it is
+instantiated again, the existing object will be returned.
+
+
+
+.. automodule:: pvp.alarm.alarm_manager
+    :members:
+    :undoc-members:
+    :autosummary:

_docs/alarm.alarm_rule.rst

@@ -0,0 +1,96 @@
+Alarm Rule
+============
+
+One :class:`.Alarm_Rule` is defined for each :class:`~.alarm.AlarmType` in :data:`.ALARM_RULES`.
+
+An alarm rule defines:
+
+* The conditions for raising different severities of an alarm
+* The dependencies between set values and alarm thresholds
+* The behavior of the alarm, specifically whether it is :attr:`~.Alarm_Rule.latch` ed.
+
+Example
+----------
+
+As an example, we'll define a ``LOW_PRESSURE`` alarm with escalating severity. A ``LOW`` severity alarm
+will be raised when measured ``PIP`` falls 10% below set ``PIP``, which will escalate to a
+``MEDIUM`` severity alarm if measured ``PIP`` falls 15% below set ``PIP`` **and** the ``LOW`` severity
+alarm has been active for at least two breath cycles.
+
+First we define the name and behavior of the alarm::
+
+    Alarm_Rule(
+        name = AlarmType.LOW_PRESSURE,
+        latch = False,
+
+In this case, ``latch == False`` means that the alarm will disappear (or be downgraded in severity)
+whenever the conditions for that alarm are no longer met. If ``latch == True``, an alarm requires manual dismissal before
+it is downgraded or disappears.
+
+Next we'll define a tuple of :class:`.Condition` objects for ``LOW`` and ``MEDIUM`` severity objects.
+
+Starting with the ``LOW`` severity alarm::
+
+    conditions = (
+        (
+        AlarmSeverity.LOW,
+        condition.ValueCondition(
+            value_name=ValueName.PIP,
+            limit=VALUES[ValueName.PIP]['safe_range'][0],
+            mode='min',
+            depends={
+                'value_name': ValueName.PIP,
+                'value_attr': 'value',
+                'condition_attr': 'limit',
+                'transform': lambda x : x-(x*0.10)
+            })
+        ),
+        # ... continued in next block
+
+Each condition is a tuple of an (:class:`.AlarmSeverity`, :class:`.Condition`). In this case,
+we use a :class:`.ValueCondition` which tests whether a value is above or below a set ``'max'`` or ``'min'``, respectively.
+For the low severity ``LOW_PRESSURE`` alarm, we test if ``ValueName.PIP`` is below (``mode='min'``) some ``limit``, which
+is initialized as the low-end of ``PIP``'s safe range.
+
+We also define a condition for updating the ``'limit'`` of the condition (``'condition_attr' : 'limit'``), from the
+:attr:`.ControlSetting.value`` field whenever ``PIP`` is updated. Specifically, we set the ``limit`` to be 10% less than the
+set ``PIP`` value by 10% with a lambda function (``lambda x : x-(x*0.10)``).
+
+Next, we define the ``MEDIUM`` severity alarm condition::
+
+    (
+    AlarmSeverity.MEDIUM,
+    condition.ValueCondition(
+        value_name=ValueName.PIP,
+        limit=VALUES[ValueName.PIP]['safe_range'][0],
+        mode='min'
+        depends={
+            'value_name': ValueName.PIP,
+            'value_attr': 'value',
+            'condition_attr': 'limit',
+            'transform': lambda x: x - (x * 0.15)
+        },
+    ) + \
+    condition.CycleAlarmSeverityCondition(
+        alarm_type = AlarmType.LOW_PRESSURE,
+        severity   = AlarmSeverity.LOW,
+        n_cycles = 2
+    ))
+
+The first ``ValueCondition`` is the same as in the ``LOW`` alarm severity condition, except that it is
+set 15% below ``PIP``.
+
+A second :class:`.CycleAlarmSeverityCondition` has been added (with ``+``) to the :class:`.ValueCondition`
+When conditions are added together, they will only return ``True`` (ie. trigger an alarm) if all of the conditions are met.
+This condition checks that the ``LOW_PRESSURE`` alarm has been active at a ``LOW`` severity for at least two cycles.
+
+Full source for this example and all alarm rules can be found `here <_modules/pvp/alarm.html>`_
+
+
+Module Documentation
+--------------------
+
+.. automodule:: pvp.alarm.rule
+    :members:
+    :undoc-members:
+    :autosummary:

_docs/alarm.condition.rst

@@ -0,0 +1,21 @@
+Alarm Condition
+===================
+
+Condition objects define conditions that can raise alarms. They are used by :class:`.Alarm_Rule` s.
+
+Each has to define a :meth:`.Condition.check` method that accepts :class:`.SensorValues` .
+The method should return ``True`` if the alarm condition is met, and ``False`` otherwise.
+
+Conditions can be added (``+``) together to make compound conditions, and a single call to ``check`` will only return true
+if both conditions return true. If any condition in the chain returns false, evaluation is stopped and
+the alarm is not raised.
+
+Conditions can
+
+.. inheritance-diagram:: pvp.alarm.condition
+
+.. automodule:: pvp.alarm.condition
+    :members:
+    :undoc-members:
+    :autosummary:
+    :show-inheritance:

_docs/alarm.rst

@@ -1,44 +1,47 @@
-alarm
+Alarm
 ==========
 
-Main Alarm Module
--------------------
 
-.. automodule:: pvp.alarm
-    :members:
-    :undoc-members:
-    :autosummary:
+Alarm System Overview
+----------------------
 
-Alarm Manager
-----------------
+* Alarms are represented as :class:`~.alarm.Alarm` objects, which are created and managed by the :class:`.Alarm_Manager`.
+* A collection of :class:`.Alarm_Rule` s define the :class:`.Condition` s for raising :class:`~.alarm.Alarm` s of different :class:`~.alarm.AlarmSeverity` .
+* The alarm manager is continuously fed :class:`~.message.SensorValues` objects during :meth:`.PVP_Gui.update_gui`, which it uses to :meth:`~.Alarm_Rule.check` each alarm rule.
+* The alarm manager emits :class:`~.alarm.Alarm` objects to the :meth:`.PVP_Gui.handle_alarm` method.
+* The alarm manager also updates alarm thresholds set as :attr:`.Condition.depends` to :meth:`.PVP_Gui.limits_updated` when control parameters are set (eg. updates the ``HIGH_PRESSURE`` alarm to be triggered 15% above some set ``PIP`` ).
 
-.. automodule:: pvp.alarm.alarm_manager
-    :members:
-    :undoc-members:
-    :autosummary:
+Alarm Modules
+---------------
 
-Alarm
-------------
+.. toctree::
+    :hidden:
 
-.. automodule:: pvp.alarm.alarm
-    :members:
-    :undoc-members:
-    :autosummary:
+    Alarm Manager <alarm.alarm_manager>
+    Alarm <alarm.alarm>
+    Alarm Rule <alarm.alarm_rule>
+    Alarm Condition <alarm.condition>
 
-Condition
------------
+.. raw:: html
+
+    <div class="software-summary">
+        <a href="alarm.alarm_manager.html"><h2>Alarm Manager</h2></a> <p>Computes alarm logic and emits alarms to the GUI</p>
+        <a href="alarm.alarm.html"><h2>Alarm</h2></a> <p>Objects used to represent alarms</p>
+        <a href="alarm.alarm_rule.html"><h2>Alarm Rule</h2></a> <p>Define conditions for triggering alarms and their behavior</p>
+        <a href="alarm.condition.html"><h2>Condition</h2></a> <p>Objects to check for alarm state</p>
+    </div>
 
-.. automodule:: pvp.alarm.condition
-    :members:
-    :undoc-members:
-    :autosummary:
 
-Alarm Rule
------------
+Main Alarm Module
+-------------------
 
-.. automodule:: pvp.alarm.rule
+.. automodule:: pvp.alarm
     :members:
     :undoc-members:
     :autosummary:
 
 
+
+
+
+

_docs/common.rst

@@ -2,16 +2,29 @@ common module
 ===================
 
 .. toctree::
+    :hidden:
     :caption: Common Modules
 
     pvp.common.values
-    pvp.common.loggers
     pvp.common.message
+    pvp.common.loggers
     pvp.common.prefs
     pvp.common.unit_conversion
     pvp.common.utils
     pvp.common.fashion
 
+.. raw:: html
+
+    <div class="software-summary">
+        <a href="pvp.common.values.html"><h2>Values</h2></a> <p>Parameterize the values used by the GUI and Controller</p>
+        <a href="pvp.common.message.html"><h2>Message</h2></a> <p>Message classes that formalize the communication API between the GUI and Controller</p>
+        <a href="pvp.common.loggers.html"><h2>Loggers</h2></a> <p>Loggers for storing system events and ventilation data</p>
+        <a href="pvp.common.prefs.html"><h2>Prefs</h2></a> <p>System configuration preferences</p>
+        <a href="pvp.common.unit_conversion.html"><h2>Unit Conversion</h2></a> <p>Functions to convert units used by the GUI!</p>
+        <a href="pvp.common.utils.html"><h2>Utils</h2></a> <p>Etc. Utility Functions</p>
+        <a href="pvp.common.fashion.html"><h2>Fashion</h2></a> <p>Decorators (largely used by HAL)</p>
+    </div>
+
 
 
 

_docs/conf.py

@@ -46,6 +46,7 @@
     'sphinx.ext.intersphinx', # include documentation from other projects
     'sphinx.ext.todo',        # todo directive
     'sphinx.ext.viewcode',
+    'sphinx.ext.inheritance_diagram',
     # 'sphinx_automodapi.automodapi',
     'sphinxcontrib.napoleon', # parse google style docstrings
     'autodocsumm',

_docs/gui.widgets.control_panel.rst

@@ -1,6 +1,8 @@
 Control Panel
 ======================
 
+The Control Panel starts and stops ventilation and controls runtime options
+
 .. automodule:: pvp.gui.widgets.control_panel
     :members:
     :undoc-members:

_docs/pvp.common.loggers.rst

@@ -1,6 +1,8 @@
-loggers
+Loggers
 =========
 
+
+
 .. automodule:: pvp.common.loggers
    :members:
    :undoc-members:

_docs/pvp.common.message.rst

@@ -1,6 +1,12 @@
-message
+Message
 ==============
 
+Message objects that define the API between modules in the system.
+
+* :class:`.SensorValues` are used to communicate sensor readings between the controller, GUI, and alarm manager
+* :class:`.ControlSetting` is used to set ventilation controls from the GUI to the controller.
+
+
 .. automodule:: pvp.common.message
    :members:
    :undoc-members:

_docs/pvp.common.prefs.rst

@@ -3,6 +3,28 @@
 Prefs
 =========
 
+Prefs set configurable parameters used throughout PVP.
+
+See :data:`.prefs._DEFAULTS` for description of all available parameters
+
+Prefs are stored in a .json file, by default located at ``~/pvp/prefs.json`` . Prefs can be manually
+changed by editing this file (when the system is not running, when the system is running use :func:`.prefs.set_pref` ).
+
+When any module in pvp is first imported, the :func:`.prefs.init` function is called
+that
+
+* Makes any directories listed in :data:`.prefs._DIRECTORIES`
+* Declares all prefs as their default values from :data:`.prefs._DEFAULTS` to ensure they are always defined
+* Loads the existing ``prefs.json`` file and updates values from their defaults
+
+Prefs can be gotten and set from anywhere in the system with :func:`.prefs.get_pref` and :func:`.prefs.set_pref` .
+Prefs are stored in a :class:`multiprocessing.Manager` dictionary which makes these methods both thread- and process-safe.
+Whenever a pref is set, the ``prefs.json`` file is updated to reflect the new value, so preferences
+are durable between runtimes.
+
+Additional ``prefs`` should be added by adding an entry in the :data:`.prefs._DEFAULTS` dict rather than hardcoding them elsewhere in the program.
+
+
 .. automodule:: pvp.common.prefs
    :members:
    :undoc-members:

_docs/pvp.common.unit_conversion.rst

@@ -1,6 +1,20 @@
-unit conversion
+Unit Conversion
 ================
 
+Functions that convert between units
+
+Each function should accept a single float as an argument and return a single float
+
+Used by the GUI to display values in different units. Widgets use these as
+
+* ``_convert_in`` functions to convert units from the base unit to the displayed unit and
+* ``_convert_out`` functions to convert units from the displayed unit to the base unit.
+
+.. note::
+
+    Unit conversions are cosmetic -- values are always kept as the base unit internally (ie. cmH2O for pressure)
+    and all that is changed is the displayed value in the GUI.
+
 .. automodule:: pvp.common.unit_conversion
    :members:
    :undoc-members:

_docs/pvp.common.values.rst

@@ -3,7 +3,11 @@
 Values
 ========
 
-Parameterization of variables and values
+Parameterization of variables and values used in PVP.
+
+:class:`.Value` objects define the existence and behavior of values, including
+creating :class:`.Display` and :class:`.Plot` widgets in the GUI, and the contents of
+:class:`.SensorValues` and :class:`.ControlSetting` s used between the GUI and controller.
 
 .. automodule:: pvp.common.values
    :members: