From 330539f7e4609187c1ec8f47487d288192a77b72 Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Wed, 16 Dec 2020 19:26:37 -0700 Subject: [PATCH 01/10] docs: display __init__() method docstrings Display the class' __init__ methods' docstrings in the online documentation. This helps users to understand the class APIs. Remove the docstring from the _XYZPacket parent class, because Sphinx was rendering that for every child class (AccelerometerPacket, GyroPacket, MagnetometerPacket, QuaternionPacket). Apparently the "autodoc_inherit_docstrings = False" setting does not work in that case. --- adafruit_bluefruit_connect/_xyz_packet.py | 5 ++--- docs/conf.py | 2 ++ 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/adafruit_bluefruit_connect/_xyz_packet.py b/adafruit_bluefruit_connect/_xyz_packet.py index c01ef5e..576bac4 100644 --- a/adafruit_bluefruit_connect/_xyz_packet.py +++ b/adafruit_bluefruit_connect/_xyz_packet.py @@ -44,9 +44,8 @@ class _XYZPacket(Packet): # _TYPE_HEADER is set by each concrete subclass. def __init__(self, x, y, z): - """Construct an _XYZPacket subclass object - from the given x, y, and z float values, and type character. - """ + # Construct an _XYZPacket subclass object + # from the given x, y, and z float values, and type character. self._x = x self._y = y self._z = z diff --git a/docs/conf.py b/docs/conf.py index 5a81e82..6d40331 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,6 +29,8 @@ "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None), } +autoclass_content = "both" + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] From 8d8b0212a62de7957c94b6ded88205f9673ac8ce Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Wed, 16 Dec 2020 19:30:07 -0700 Subject: [PATCH 02/10] docs: explain ButtonPacket.pressed property values As alluded in the __init__() docstring, explain that the "pressed" property is False when a button is released. --- adafruit_bluefruit_connect/button_packet.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adafruit_bluefruit_connect/button_packet.py b/adafruit_bluefruit_connect/button_packet.py index 858e193..8119dd2 100644 --- a/adafruit_bluefruit_connect/button_packet.py +++ b/adafruit_bluefruit_connect/button_packet.py @@ -105,7 +105,7 @@ def button(self): @property def pressed(self): - """True if button is pressed.""" + """``True`` if button is pressed, or ``False`` if it is released.""" return self._pressed From be411a10f1eaa09c147421217286a72d55332e7b Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Wed, 16 Dec 2020 19:38:15 -0700 Subject: [PATCH 03/10] docs: fix grammar in ButtonPacket.pressed docstring --- adafruit_bluefruit_connect/button_packet.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adafruit_bluefruit_connect/button_packet.py b/adafruit_bluefruit_connect/button_packet.py index 8119dd2..e9a4666 100644 --- a/adafruit_bluefruit_connect/button_packet.py +++ b/adafruit_bluefruit_connect/button_packet.py @@ -66,7 +66,8 @@ def __init__(self, button, pressed): """Construct a ButtonPacket from a button name and the button's state. :param str button: a single character denoting the button - :param bool pressed: ``True`` if button is pressed; ``False`` if it is release. + :param bool pressed: ``True`` if button is pressed; ``False`` if it is + released. """ # This check will catch wrong length and also non-sequence args (like an int). try: From 4b6bf7148b7db7f924968f2d19b221a9fc351ccf Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 12:18:31 -0700 Subject: [PATCH 04/10] docs: fix Adafruit_CircuitPython_BluefruitConnect links Some links went to the Adafruit_CircuitPython_ble project instead of this Adafruit_CircuitPython_BluefruitConnect project (possibly a bad copy-and-paste). Update those links to point to this project instead. --- README.rst | 2 +- docs/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 5d20fe7..638bc8a 100644 --- a/README.rst +++ b/README.rst @@ -75,7 +75,7 @@ Contributing ============ Contributions are welcome! Please read our `Code of Conduct -`_ +`_ before contributing to help this project stay welcoming. Documentation diff --git a/docs/index.rst b/docs/index.rst index 41c37eb..442e206 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,7 +29,7 @@ Table of Contents .. toctree:: :caption: Other Links - Download + Download CircuitPython Reference Documentation CircuitPython Support Forum Discord Chat From 338f12a9c4b11a470ee9cbbaa29c82abb0d95729 Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 12:35:39 -0700 Subject: [PATCH 05/10] docs: simplify and improve main module documentation Remove the reference to the Feather nRF52840 Express, since this library can be used on many boards now (eg. Circuit Playground BlueFruit). Update BlueFruit Connect App link to point to Adafruit's main app web page, rather than the iOS-specific page, since this app is available for Andriod too now. Remove the GitHub releases link and add a link to to circuitpython.org's download page instead, because the GitHub release pages point there now. --- adafruit_bluefruit_connect/__init__.py | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/adafruit_bluefruit_connect/__init__.py b/adafruit_bluefruit_connect/__init__.py index c07e956..24a842d 100644 --- a/adafruit_bluefruit_connect/__init__.py +++ b/adafruit_bluefruit_connect/__init__.py @@ -23,24 +23,13 @@ `adafruit_bluefruit_connect` ============================ -This module helps you to communicate with the Adafruit Bluefruit Connect app or use its protocols. +This module helps you to communicate with the `Adafruit Bluefruit Connect App +`_ or use its protocols with +boards that run `Adafruit CircuitPython firmware +`_. * Author(s): Dan Halbert for Adafruit Industries -Implementation Notes --------------------- - -**Hardware:** - - Adafruit Feather nRF52840 Express - -**Software and Dependencies:** - -* Adafruit Bluefruit LE Connect App - https://learn.adafruit.com/bluefruit-le-connect-for-ios (also available for Android) -* Adafruit CircuitPython firmware for the supported boards: - https://github.com/adafruit/circuitpython/releases - """ # imports From 9e82238af9838be09afe0d3db868eb14488ae670 Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 13:27:58 -0700 Subject: [PATCH 06/10] docs: fix sphinx syntax for Packet "checksum" parameter Prior to this change, Sphinx incorrectly indented the "checksum" list item. Wrap and indent the lines at a proper length so that Sphinx renders this list item the same as the other items. --- adafruit_bluefruit_connect/packet.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adafruit_bluefruit_connect/packet.py b/adafruit_bluefruit_connect/packet.py index 664ed48..621c3b7 100644 --- a/adafruit_bluefruit_connect/packet.py +++ b/adafruit_bluefruit_connect/packet.py @@ -39,8 +39,8 @@ class Packet: - '!' - The first byte is always an exclamation point. - *type* - A single byte designating the type of packet: b'A', b'B', etc. - *data ...* - Multiple bytes of data, varying by packet type. - - *checksum* - A single byte checksum, computed by adding up all the data bytes and - inverting the sum. + - *checksum* - A single byte checksum, computed by adding up all the data + bytes and inverting the sum. This is an abstract class. """ From 4e4675c02cb60c0eb801a3ed85c37caeeda4f375 Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 13:31:51 -0700 Subject: [PATCH 07/10] docs: further explain ButtonPacket.button property Explain that this attribute corresponds to whatever the user has pressed or released. --- adafruit_bluefruit_connect/button_packet.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adafruit_bluefruit_connect/button_packet.py b/adafruit_bluefruit_connect/button_packet.py index e9a4666..f6b5c5c 100644 --- a/adafruit_bluefruit_connect/button_packet.py +++ b/adafruit_bluefruit_connect/button_packet.py @@ -101,7 +101,8 @@ def to_bytes(self): @property def button(self): - """A single character string (not bytes) specifying the button.""" + """A single character string (not bytes) specifying the button that + the user pressed or released.""" return self._button @property From dc3cd8356a5130f2d352a5a90774213838960cac Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 14:07:27 -0700 Subject: [PATCH 08/10] docs: autolink "tuple" in ColorPacket Link to Python's documentation for the "tuple" built-in type so readers can easily understand this term. --- adafruit_bluefruit_connect/color_packet.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/adafruit_bluefruit_connect/color_packet.py b/adafruit_bluefruit_connect/color_packet.py index 9486a5e..f3a963d 100644 --- a/adafruit_bluefruit_connect/color_packet.py +++ b/adafruit_bluefruit_connect/color_packet.py @@ -44,10 +44,10 @@ class ColorPacket(Packet): _TYPE_HEADER = b"!C" def __init__(self, color): - """Construct a ColorPacket from a 3-tuple of RGB values, - or from an int color value 0xRRGGBB. + """Construct a ColorPacket from a 3-element :class:`tuple` of RGB + values, or from an int color value 0xRRGGBB. - :param tuple/int color: an RGB tuple ``(red, green, blue)`` + :param tuple/int color: an RGB :class:`tuple` ``(red, green, blue)`` or an int color value ``0xRRGGBB`` """ if isinstance(color, int): From 675a687020c5b219d9c1d3e42530a744012f1378 Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 14:08:17 -0700 Subject: [PATCH 09/10] docs: expand ColorPacket.packet documentation Explain that this comes from a user's choice in the application. --- adafruit_bluefruit_connect/color_packet.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adafruit_bluefruit_connect/color_packet.py b/adafruit_bluefruit_connect/color_packet.py index f3a963d..a58f4a8 100644 --- a/adafruit_bluefruit_connect/color_packet.py +++ b/adafruit_bluefruit_connect/color_packet.py @@ -75,7 +75,8 @@ def to_bytes(self): @property def color(self): - """A tuple(red, green blue).""" + """A :class:`tuple` ``(red, green blue)`` representing the color the + user chose in the BlueFruit Connect app.""" return self._color From 6298d9b36ef746977218e85487f93a183399e47e Mon Sep 17 00:00:00 2001 From: Ken Dreyer Date: Fri, 18 Dec 2020 15:16:44 -0700 Subject: [PATCH 10/10] docs: update docstring for QuaternionPacket class The QuaternionPacket's documentation was copy-pasted from the _XYZPacket class. Write a new docstring for the QuaternionPacket class to describe what it does. --- adafruit_bluefruit_connect/quaternion_packet.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/adafruit_bluefruit_connect/quaternion_packet.py b/adafruit_bluefruit_connect/quaternion_packet.py index 2e9e927..7b86efb 100644 --- a/adafruit_bluefruit_connect/quaternion_packet.py +++ b/adafruit_bluefruit_connect/quaternion_packet.py @@ -35,7 +35,8 @@ class QuaternionPacket(_XYZPacket): - """A packet of x, y, z float values. Used for several different Bluefruit controller packets.""" + """Device Motion data to describe device attitude. This data is derived + from Accelerometer, Gyro, and Magnetometer readings.""" # Use _XYZPacket to handle x, y, z, and add w.