make actuation_range be documented as a property. Simplify how to get throttle property.

Author: dhalbert

adafruit_motor/motor.py

@@ -51,27 +51,21 @@ class DCMotor:
     def __init__(self, positive_pwm, negative_pwm):
         self._positive = positive_pwm
         self._negative = negative_pwm
+        self._throttle = None
 
     @property
     def throttle(self):
-        """How much power is being delivered to the motor. Values range from ``-1.0`` (full
-           throttle reverse) to ``1.0`` (full throttle forwards.) ``0`` will stop the motor from
-           spinning and ``None`` will let the motor spin freely."""
-        if self._positive.duty_cycle == 0 and self._negative.duty_cycle == 0:
-            return None
-        if self._positive.duty_cycle == 0xffff and self._negative.duty_cycle == 0xffff:
-            return float(0)
-        if self._positive.duty_cycle > 0 and self._negative.duty_cycle > 0:
-            raise RuntimeError("PWMs in invalid state")
-        value = max(self._positive.duty_cycle, self._negative.duty_cycle) / 0xffff
-        if self._negative.duty_cycle > 0:
-            return -1 * value
-        return value
+        """Motor speed, ranging from -1.0 (full speed reverse) to 1.0 (full speed forward),
+        or ``None``.
+        If ``None``, both PWMs are turned full off. If ``0.0``, both PWMs are turned full on.
+        """
+        return self._throttle
 
     @throttle.setter
     def throttle(self, value):
         if value is not None and (value > 1.0 or value < -1.0):
             raise ValueError("Throttle must be None or between -1.0 and 1.0")
+        self._throttle = value
         if value is None:
             self._positive.duty_cycle = 0
             self._negative.duty_cycle = 0

adafruit_motor/servo.py

@@ -42,9 +42,9 @@ class _BaseServo: # pylint: disable-msg=too-few-public-methods
        :param int max_pulse: The maximum pulse length of the servo in microseconds."""
     def __init__(self, pwm_out, *, min_pulse=750, max_pulse=2250):
         self._pwm_out = pwm_out
-        self.set_pulse_widths(min_pulse, max_pulse)
+        self.set_pulse_width_range(min_pulse, max_pulse)
 
-    def set_pulse_widths_range(self, min_pulse=750, max_pulse=2250):
+    def set_pulse_width_range(self, min_pulse=750, max_pulse=2250):
         """Change min and max pulse widths."""
         self._min_duty = int((min_pulse * self._pwm_out.frequency) / 1000000 * 0xffff)
         max_duty = (max_pulse * self._pwm_out.frequency) / 1000000 * 0xffff
@@ -93,10 +93,11 @@ class Servo(_BaseServo):
          get a wider range of movement. But if you go too low or too high,
          the servo mechanism may hit the end stops, buzz, and draw extra current as it stalls.
          Test carefully to find the safe minimum and maximum.
-"""
+    """
     def __init__(self, pwm_out, *, actuation_range=180, min_pulse=750, max_pulse=2250):
         super().__init__(pwm_out, min_pulse=min_pulse, max_pulse=max_pulse)
         self.actuation_range = actuation_range
+        """The physical range of motion of the servo in degrees."""
         self._pwm = pwm_out
 
     @property

docs/conf.py

@@ -74,6 +74,16 @@
 # If this is True, todo emits a warning for each TODO entries. The default is False.
 todo_emit_warnings = True
 
+# Avoid an `= None` on instance attributes with their own doc strings.
+# Workaround from here: https://github.com/sphinx-doc/sphinx/issues/2044#issuecomment-285888160
+#
+from sphinx.ext.autodoc import (
+    ClassLevelDocumenter, InstanceAttributeDocumenter)
+
+def iad_add_directive_header(self, sig):
+    ClassLevelDocumenter.add_directive_header(self, sig)
+
+InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header
 
 # -- Options for HTML output ----------------------------------------------