Add Sphinx usage documentation (#2)

Adds documentation describing every public method and data structure that the Python API makes available. The documentation uses Sphinx's autodoc extension to pull information from the docstrings. I've also added any missing docstrings and clarified some older ones.

Author: velovix

.gitignore

@@ -1,3 +1,6 @@
 *.egg-info
 .idea/
 *.pyc
+
+_build/
+_static/

README.rst

@@ -2,6 +2,14 @@
 BrainFrame Python API
 =====================
 
+.. image:: https://readthedocs.org/projects/brainframe-python-api/badge/?version=latest
+   :target: https://brainframe-python-api.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+.. image:: https://github.com/aotuai/brainframe_python/workflows/Publish%20package/badge.svg
+   :target: https://github.com/aotuai/brainframe_python/actions
+   :alt: Publish Packages CI Status
+
 This library is a Python wrapper around the BrainFrame REST API. It allows for
 easy interaction with a BrainFrame server.
 
@@ -34,3 +42,12 @@ you are using.
 .. code-block:: bash
 
    pip3 install brainframe-api==0.26.0
+
+Documentation
+-------------
+
+Documentation for this library is available on `ReadTheDocs`_.
+
+.. _`ReadTheDocs`:
+   https://brainframe-python-api.readthedocs.io/en/latest/
+

brainframe/api/bf_codecs/__init__.py

@@ -10,7 +10,8 @@
     DirectionType,
 )
 from .config_codecs import StreamConfiguration, ConnType
-from .detection_codecs import Attribute, Detection, Identity
+from .identity_codecs import Identity, Encoding
+from .detection_codecs import Attribute, Detection
 from .zone_codecs import Zone, ZoneStatus
 from .plugin_codecs import (
     PluginOption,
@@ -19,9 +20,8 @@
     OptionType,
     SizeType,
 )
-from .encoding_codecs import Encoding
-from .premises_codec import Premises
-from .user_codec import User, RoleType
+from .premises_codecs import Premises
+from .user_codecs import User, RoleType
 from .license_codecs import (
     LicenseTerms,
     LicenseInfo,

brainframe/api/bf_codecs/alarm_codecs.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import List, Optional
 
 from .base_codecs import Codec
 from .condition_codecs import ZoneAlarmCountCondition, ZoneAlarmRateCondition
@@ -7,18 +7,40 @@
 class ZoneAlarm(Codec):
     """This is the configuration for an alarm."""
 
-    def __init__(self, *, name, count_conditions, rate_conditions,
-                 use_active_time, active_start_time, active_end_time,
-                 id_=None, zone_id=None, stream_id=None):
-        self.name = name
-        self.id = id_
-        self.zone_id = zone_id
-        self.stream_id = stream_id
+    def __init__(self, *,
+                 name: str,
+                 count_conditions: List[ZoneAlarmCountCondition],
+                 rate_conditions: List[ZoneAlarmRateCondition],
+                 use_active_time: bool,
+                 active_start_time: str,
+                 active_end_time: str,
+                 id_: int = None,
+                 zone_id: int = None,
+                 stream_id: int = None):
+        self.name: str = name
+        """A friendly name for the zone alarm"""
+        self.id: int = id_
+        """A unique identifier"""
+        self.zone_id: int = zone_id
+        """The ID of the zone this alarm is associated with"""
+        self.stream_id: int = stream_id
+        """The ID of the stream the associated zone is in"""
         self.count_conditions: List[ZoneAlarmCountCondition] = count_conditions
+        """All count conditions for this alarm"""
         self.rate_conditions: List[ZoneAlarmRateCondition] = rate_conditions
-        self.use_active_time = use_active_time
-        self.active_start_time = active_start_time
-        self.active_end_time = active_end_time
+        """All rate conditions for this alarm"""
+        self.use_active_time: bool = use_active_time
+        """If True, the alarm will only be triggered when the current time is
+        between the active_start_time and active_end_time.
+        """
+        self.active_start_time: str = active_start_time
+        """The time of day where this alarm starts being active, in the format
+        "hh:mm:ss"
+        """
+        self.active_end_time: str = active_end_time
+        """The time of day where this alarm starts being active, in the format
+        "hh:mm:ss"
+        """
 
     def to_dict(self):
         d = dict(self.__dict__)
@@ -48,24 +70,36 @@ def from_dict(d):
 
 
 class Alert(Codec):
-    """This is sent when an Alarm has been triggered.
-    An alert can be sent WITHOUT an end_time, but never without a start_time.
+    """This is sent when an Alarm has been triggered."""
 
-    self.verified_as can be True, False or None.
-        If True, then this alert was labeled by a person as being legitimate
-        If False,then this alert was labeled by a person as being a false alarm
-        If None, then this alert has not been labeled yet.
-    """
-
-    def __init__(self, *, alarm_id, zone_id, stream_id, start_time, end_time,
-                 verified_as, id_=None):
-        self.id = id_
-        self.alarm_id = alarm_id
-        self.zone_id = zone_id
-        self.stream_id = stream_id
-        self.start_time = start_time
-        self.end_time = end_time
-        self.verified_as = verified_as
+    def __init__(self, *,
+                 alarm_id: int,
+                 zone_id: int,
+                 stream_id: int,
+                 start_time: float,
+                 end_time: float,
+                 verified_as: Optional[bool],
+                 id_: int = None):
+        self.id: int = id_
+        """A unique identifier"""
+        self.alarm_id: int = alarm_id
+        """The ID of the alarm that this alert came from"""
+        self.zone_id: int = zone_id
+        """The ID of the zone this alert pertains to"""
+        self.stream_id: int = stream_id
+        """The ID of the stream this alert pertains to"""
+        self.start_time: float = start_time
+        """When the event started happening, in Unix Time (seconds)"""
+        self.end_time: Optional[float] = end_time
+        """When the event stopped happening, in Unix Time (seconds), or None
+        if the alert is ongoing.
+        """
+        self.verified_as: Optional[bool] = verified_as
+        """
+        - If True, then this alert was labeled by a person as legitimate
+        - If False, then this alert was labeled by a person as a false alarm
+        - If None, then this alert has not been reviewed by a person
+        """
 
     def to_dict(self):
         d = dict(self.__dict__)

brainframe/api/bf_codecs/condition_codecs.py

@@ -1,4 +1,5 @@
 from enum import Enum
+from typing import Optional
 
 from .base_codecs import Codec
 from .detection_codecs import Attribute
@@ -13,6 +14,10 @@
 
 
 class CountConditionTestType(Enum):
+    """Defines the way a count condition compares the actual value to the
+    alarm's test value.
+    """
+
     GREATER_THAN = ">"
     LESS_THAN = "<"
     EQUAL_TO = "="
@@ -24,6 +29,12 @@ def values(cls):
 
 
 class IntersectionPointType(Enum):
+    """The point on a detection that must be inside a zone for the detection to
+    count as being inside the zone. The most commonly used intersection point
+    is BOTTOM, which counts a detection as being inside a zone if the bottom
+    center point of the detection in the zone.
+    """
+
     BOTTOM = "bottom"
     TOP = "top"
     LEFT = "left"
@@ -40,20 +51,38 @@ class ZoneAlarmCountCondition(Codec):
     of objects in a zone to some number.
     """
 
-    TestType = CountConditionTestType
-    IntersectionPointType = IntersectionPointType
-
-    def __init__(self, *, test, check_value, with_class_name, with_attribute,
-                 window_duration, window_threshold, intersection_point,
-                 id_=None):
-        self.test = test
-        self.check_value = check_value
-        self.with_class_name = with_class_name
-        self.with_attribute = with_attribute
-        self.window_duration = window_duration
-        self.window_threshold = window_threshold
-        self.intersection_point = intersection_point
-        self.id = id_
+    def __init__(self, *,
+                 test: CountConditionTestType,
+                 check_value: int,
+                 with_class_name: str,
+                 with_attribute: Optional[Attribute],
+                 window_duration: float,
+                 window_threshold: float,
+                 intersection_point: IntersectionPointType,
+                 id_: int = None):
+        self.test: CountConditionTestType = test
+        """The way that the check value will be compared to the actual count
+        """
+        self.check_value: int = check_value
+        """The value to test the actual count against"""
+        self.with_class_name: str = with_class_name
+        """The class name of the objects to count"""
+        self.with_attribute: Optional[Attribute] = with_attribute
+        """If provided, only objects that have this attribute value will be
+        counted.
+        """
+        self.window_duration: float = window_duration
+        """The sliding window duration for this condition"""
+        self.window_threshold: float = window_threshold
+        """The portion of time during the sliding window duration that this
+        condition must be true in order for the associated alarm to trigger
+        """
+        self.intersection_point: IntersectionPointType = intersection_point
+        """The point in each detection that must be within the zone in order
+        for that detection to be counted as in that zone
+        """
+        self.id: int = id_
+        """A unique identifier"""
 
     def __repr__(self):
         condition_str = condition_test_map[self.test.value]
@@ -93,6 +122,10 @@ def from_dict(d: dict):
 
 
 class RateConditionTestType(Enum):
+    """Defines the way a rate condition compares the actual rate value to the
+    alarm's test value.
+    """
+
     GREATER_THAN_OR_EQUAL_TO = ">="
     LESS_THAN_OR_EQUAL_TO = "<="
 
@@ -102,6 +135,8 @@ def values(cls):
 
 
 class DirectionType(Enum):
+    """Defines the direction of flow that a rate condition pertains to."""
+
     ENTERING = "entering"
     EXITING = "exiting"
     ENTERING_OR_EXITING = "entering_or_exiting"
@@ -112,27 +147,43 @@ def values(cls):
 
 
 class ZoneAlarmRateCondition(Codec):
-    """A condition that must be met for an alarm to go off. Compares the rate of
-    change in the count of some object against a test value.
+    """A condition that must be met for an alarm to go off. Compares the rate
+    of change in the count of some object against a test value.
     """
 
-    TestType = RateConditionTestType
-    DirectionType = DirectionType
-
     direction_map = {DirectionType.ENTERING: "entered",
                      DirectionType.EXITING: "exited",
                      DirectionType.ENTERING_OR_EXITING: "entered or exited"}
 
-    def __init__(self, *, test, duration, change, direction, with_class_name,
-                 with_attribute, intersection_point, id_=None):
-        self.test = test
-        self.duration = duration
-        self.change = change
-        self.direction = direction
-        self.with_class_name = with_class_name
-        self.with_attribute = with_attribute
-        self.intersection_point = intersection_point
-        self.id = id_
+    def __init__(self, *,
+                 test: RateConditionTestType,
+                 duration: float,
+                 change: float,
+                 direction: DirectionType,
+                 with_class_name: str,
+                 with_attribute: Optional[Attribute],
+                 intersection_point: IntersectionPointType,
+                 id_: int = None):
+        self.test: RateConditionTestType = test
+        """The way that the change value will be compared to the actual rate"""
+        self.duration: float = duration
+        """The time in seconds for this rate change to occur"""
+        self.change: float = change
+        """The rate change value to compare the actual rate value against"""
+        self.direction: DirectionType = direction
+        """The direction of flow this condition tests for"""
+        self.with_class_name: str = with_class_name
+        """The class name of the objects to measure rate of change for"""
+        self.with_attribute: Optional[Attribute] = with_attribute
+        """If provided, only objects that have this attribute will be counted
+        in the rate calculation
+        """
+        self.intersection_point: IntersectionPointType = intersection_point
+        """The point in each detection that must be within the zone in order
+        for that detection to be counted as in that zone
+        """
+        self.id: int = id_
+        """A unique identifier"""
 
     def __repr__(self):
         condition_str = condition_test_map[self.test.value]