address comments so far; fix sphinx build

Author: dhalbert

adafruit_ble/__init__.py

@@ -58,11 +58,12 @@ class BLEConnection:
     Represents a connection to a peer BLE device.
     It acts as a map from a `Service` type to a `Service` instance for the connection.
 
-    :param bleio_connection _bleio.connection
+    :param bleio_connection _bleio.Connection
+      Wrap the native `_bleio.Connection` object.
     """
     def __init__(self, bleio_connection):
         self._bleio_connection = bleio_connection
-        # _bleio.Service objects representing services found during discoery.
+        # _bleio.Service objects representing services found during discovery.
         self._discovered_bleio_services = {}
         # Service objects that wrap remote services.
         self._constructed_services = {}
@@ -186,9 +187,10 @@ def start_scan(self, *advertisement_types, buffer_size=512, extended=False, time
              window must be <= interval.
         :param int minimum_rssi: the minimum rssi of entries to return.
         :param bool active: request and retrieve scan responses for scannable advertisements.
-        :returns: iterable: If any ``advertisement_types`` are given,
+        :return: If any ``advertisement_types`` are given,
            only Advertisements of those types are produced by the returned iterator.
            If none are given then `Advertisement` objects will be returned.
+        :rtype: iterable
         """
         prefixes = b""
         if advertisement_types:
@@ -218,8 +220,8 @@ def connect(self, advertisement, *, timeout=4):
 
         :param advertisement Advertisement: An `Advertisement` or a subclass of `Advertisement`
         :param timeout float: how long to wait for a connection
-        :returns the connection to the peer
-        :rtype BLEConnection
+        :return: the connection to the peer
+        :rtype: BLEConnection
         """
         connection = self._adapter.connect(advertisement.address, timeout=timeout)
         self._connection_cache[connection] = BLEConnection(connection)

adafruit_ble/attributes/__init__.py

@@ -33,7 +33,36 @@
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE.git"
 
 class Attribute:
-    """Constants describing security levels."""
+    """Constants describing security levels.
+
+      .. data:: NO_ACCESS
+
+         security mode: access not allowed
+
+      .. data:: OPEN
+
+         security_mode: no security (link is not encrypted)
+
+      .. data:: ENCRYPT_NO_MITM
+
+         security_mode: unauthenticated encryption, without man-in-the-middle protection
+
+      .. data:: ENCRYPT_WITH_MITM
+
+         security_mode: authenticated encryption, with man-in-the-middle protection
+
+      .. data:: LESC_ENCRYPT_WITH_MITM
+
+         security_mode: LESC encryption, with man-in-the-middle protection
+
+      .. data:: SIGNED_NO_MITM
+
+         security_mode: unauthenticated data signing, without man-in-the-middle protection
+
+      .. data:: SIGNED_WITH_MITM
+
+         security_mode: authenticated data signing, without man-in-the-middle protection
+"""
     NO_ACCESS = _bleio.Attribute.NO_ACCESS
     OPEN = _bleio.Attribute.OPEN
     ENCRYPT_NO_MITM = _bleio.Attribute.ENCRYPT_NO_MITM

adafruit_ble/characteristics/__init__.py

@@ -39,6 +39,7 @@
 class Characteristic:
     """
     Top level Characteristic class that does basic binding.
+
     :param UUID uuid: The uuid of the characteristic
     :param int properties: The properties of the characteristic,
        specified as a bitmask of these values bitwise-or'd together:
@@ -57,24 +58,37 @@ class Characteristic:
     :param bool fixed_length: True if the characteristic value is of fixed length.
     :param buf initial_value: The initial value for this characteristic. If not given, will be
        filled with zeros.
-    :return: the new Characteristic.
 
+    .. data:: BROADCAST
+
+       property: allowed in advertising packets
+
+    .. data:: INDICATE
+
+         property: server will indicate to the client when the value is set and wait for a response
+
+    .. data:: NOTIFY
+
+       property: server will notify the client when the value is set
+
+    .. data:: READ
+
+       property: clients may read this characteristic
+
+    .. data:: WRITE
+
+       property: clients may write this characteristic; a response will be sent back
+
+    .. data:: WRITE_NO_RESPONSE
+
+       property: clients may write this characteristic; no response will be sent back
 """
     BROADCAST = _bleio.Characteristic.BROADCAST
-    """Property: allowed in advertising packets."""
     INDICATE = _bleio.Characteristic.INDICATE
-    """Property: server will indicate to the client when the value is set
-    and wait for a response.
-    """
     NOTIFY = _bleio.Characteristic.NOTIFY
-    """Property: lServer will notify the client when the value is set."""
     READ = _bleio.Characteristic.READ
-    """Property: clients may read this characteristic."""
     WRITE = _bleio.Characteristic.WRITE
-    """Property: clients may write this characteristic; a response will be sent back."""
     WRITE_NO_RESPONSE = _bleio.Characteristic.WRITE_NO_RESPONSE
-    """Property: clients may write this characteristic; no response will be sent back."""
-
 
     def __init__(self, *, uuid=None, properties=0,
                  read_perm=Attribute.OPEN, write_perm=Attribute.OPEN,

adafruit_ble/services/standard/device_info.py

@@ -48,8 +48,8 @@
 import sys
 import microcontroller
 
-from ..core import Service
-from ...core.uuid import StandardUUID
+from .. import Service
+from ...uuid import StandardUUID
 from ...characteristics.string import FixedStringCharacteristic
 
 __version__ = "0.0.0-auto.0"

adafruit_ble/services/standard/standard.py

@@ -29,10 +29,10 @@
 
 import time
 
-from ..core import Service
-from ...core.uuid import StandardUUID
+from .. import Service
+from ...uuid import StandardUUID
 from ..characteristics.string import StringCharacteristic
-from ..characteristics.core import StructCharacteristic
+from ..characteristics import StructCharacteristic
 from ..characteristics.int import Uint8Characteristic
 
 __version__ = "0.0.0-auto.0"

docs/api.rst

@@ -8,6 +8,7 @@
 
    top_level
    advertising
+   attributes
    characteristics
    services
    uuid

docs/attributes.rst

@@ -0,0 +1,5 @@
+`adafruit_ble.attributes`
+====================================================
+
+.. automodule:: adafruit_ble.attributes
+   :members:

docs/bleio_mock.py

@@ -1,13 +1,20 @@
 class Attribute:
-    OPEN = 0
     NO_ACCESS = 0
+    OPEN = 0
+    ENCRYPT_NO_MITM = 0
+    ENCRYPT_WITH_MITM = 0
+    LESC_ENCRYPT_WITH_MITM = 0
+    SIGNED_NO_MITM = 0
+    SIGNED_WITH_MITM = 0
 
 class UUID:
     def __init__(self, uuid):
         pass
 
 class Characteristic:
+    BROADCAST = 0
     READ = 0
     WRITE = 0
     NOTIFY = 0
+    INDICATE = 0
     WRITE_NO_RESPONSE = 0