Merge pull request #40 from jposada202020/improving_docs

improving_docs
adafruit · Apr 27, 2021 · 0a51775 · 0a51775
2 parents 3c0bf24 + 24539d6
commit 0a51775
Show file tree

Hide file tree

Showing 15 changed files with 238 additions and 69 deletions.
diff --git a/README.rst b/README.rst
@@ -60,15 +60,13 @@ To install in a virtual environment in your current project:
 
 Usage Example
 =============
-.. code-block:: python
+.. code-block:: python3
 
     import time
     import board
-    import busio
     from adafruit_lsm6ds.lsm6dsox import LSM6DSOX
 
-    i2c = busio.I2C(board.SCL, board.SDA)
-
+    i2c = board.I2C()  # uses board.SCL and board.SDA
     sox = LSM6DSOX(i2c)
 
     while True:

diff --git a/adafruit_lsm6ds/__init__.py b/adafruit_lsm6ds/__init__.py
@@ -36,30 +36,40 @@
 
 **Hardware:**
 
-* Adafruit LSM6DSOX Breakout <https://www.adafruit.com/products/4438>
+* Adafruit `LSM6DSOX 6 DoF Accelerometer and Gyroscope
+  <https://www.adafruit.com/product/4438>`_
 
-* Adafruit ISM330DHCX Breakout <https://www.adafruit.com/product/4502>
+* Adafruit `ISM330DHCX - 6 DoF IMU - Accelerometer and Gyroscope
+  <https://www.adafruit.com/product/4502>`_
 
-* Adafruit LSM6DSO32  Breakout <https://www.adafruit.com/product/4692>
+* Adafruit `LSM6DSO32 6-DoF Accelerometer and Gyroscope
+  <https://www.adafruit.com/product/4692>`_
 
-* Adafruit LSM6DS33 Breakout <https://www.adafruit.com/product/4480>
+* Adafruit `LSM6DS33 6-DoF Accel + Gyro IMU
+  <https://www.adafruit.com/product/4480>`_
 
-* Adafruit ISM330DHCX + LIS3MDL FEATHERWING <https://www.adafruit.com/product/4569>
+* Adafruit `ISM330DHCX + LIS3MDL FeatherWing - High Precision 9-DoF IMU
+  <https://www.adafruit.com/product/4569>`_
 
-* Adafruit LSM6DSOX + LIS3MDL - 9 DOF IMU Breakout <https://www.adafruit.com/product/4517>
+* Adafruit `LSM6DSOX + LIS3MDL - Precision 9 DoF IMU
+  <https://www.adafruit.com/product/4517>`_
 
-* Adafruit LSM6DS33 + LIS3MDL - 9 DOF IMU Breakout <https://www.adafruit.com/product/4485>
+* Adafruit `LSM6DS33 + LIS3MDL - 9 DoF IMU with Accel / Gyro / Mag
+  <https://www.adafruit.com/product/4485>`_
+
+* Adafruit `LSM6DSOX + LIS3MDL FeatherWing - Precision 9-DoF IMU
+  <https://www.adafruit.com/product/4565>`_
 
-* Adafruit LSM6DSOX + LIS3MDL  9 DOF IMU FeatherWing <https://www.adafruit.com/product/4565>
 
 **Software and Dependencies:**
 
 * Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
+  https://circuitpython.org/downloads
+* Adafruit's Bus Device library:
+  https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+* Adafruit's Register library:
+  https://github.com/adafruit/Adafruit_CircuitPython_Register
 
-* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
-* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
 """
 
 __version__ = "0.0.0-auto.0"
@@ -92,7 +102,7 @@ def add_values(cls, value_tuples):
 
     @classmethod
     def is_valid(cls, value):
-        "Returns true if the given value is a member of the CV"
+        """Returns true if the given value is a member of the CV"""
         return value in cls.string
 
 
@@ -164,7 +174,8 @@ class LSM6DS:  # pylint: disable=too-many-instance-attributes
     """Driver for the LSM6DSOX 6-axis accelerometer and gyroscope.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LSM6DSOX is connected to.
-    :param address: The I2C address of the sensor
+    :param int address: TThe I2C device address. Defaults to :const:`0x6A`
+
     """
 
     # ROUnaryStructs:
@@ -173,8 +184,6 @@ class LSM6DS:  # pylint: disable=too-many-instance-attributes
     # Structs
     _raw_accel_data = Struct(_LSM6DS_OUTX_L_A, "<hhh")
     _raw_gyro_data = Struct(_LSM6DS_OUTX_L_G, "<hhh")
-    _raw_temp_data = Struct(_LSM6DS_OUT_TEMP_L, "<bb")
-
     # RWBits:
 
     _accel_range = RWBits(2, _LSM6DS_CTRL1_XL, 2)
@@ -249,16 +258,6 @@ def _add_accel_ranges():
             )
         )
 
-    @property
-    def temperature(self):
-        """The temperature, in degrees Celsius."""
-        raw_temp_data = self._raw_temp_data
-
-        temperature_raw = raw_temp_data[0] | (raw_temp_data[1] << 8)
-        temperature_c = temperature_raw / 16.0 + 25.0
-
-        return temperature_c
-
     @property
     def acceleration(self):
         """The x, y, z acceleration values returned in a 3-tuple and are in m / s ^ 2."""
@@ -290,7 +289,7 @@ def _scale_gyro_data(self, raw_measurement):
     @property
     def accelerometer_range(self):
         """Adjusts the range of values that the sensor can measure, from +/- 2G to +/-16G
-        Note that larger ranges will be less accurate. Must be an `AccelRange`"""
+        Note that larger ranges will be less accurate. Must be an ``AccelRange``"""
         return self._cached_accel_range
 
     # pylint: disable=no-member
@@ -305,7 +304,7 @@ def accelerometer_range(self, value):
     @property
     def gyro_range(self):
         """Adjusts the range of values that the sensor can measure, from 125 Degrees/s to 2000
-        degrees/s. Note that larger ranges will be less accurate. Must be a `GyroRange`."""
+        degrees/s. Note that larger ranges will be less accurate. Must be a ``GyroRange``."""
         return self._cached_gyro_range
 
     @gyro_range.setter
@@ -329,7 +328,7 @@ def _set_gyro_range(self, value):
 
     @property
     def accelerometer_data_rate(self):
-        """Select the rate at which the accelerometer takes measurements. Must be a `Rate`"""
+        """Select the rate at which the accelerometer takes measurements. Must be a ``Rate``"""
         return self._accel_data_rate
 
     @accelerometer_data_rate.setter
@@ -343,7 +342,7 @@ def accelerometer_data_rate(self, value):
 
     @property
     def gyro_data_rate(self):
-        """Select the rate at which the gyro takes measurements. Must be a `Rate`"""
+        """Select the rate at which the gyro takes measurements. Must be a ``Rate``"""
         return self._gyro_data_rate
 
     @gyro_data_rate.setter

diff --git a/adafruit_lsm6ds/ism330dhcx.py b/adafruit_lsm6ds/ism330dhcx.py
@@ -2,7 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-This module provides the ISM330DHCX subclass of LSM6DS for using ISM330DHCX sensors.
+This module provides the `adafruit_lsm6ds.ism330dhcx` subclass of LSM6DS sensors
+==================================================================================
 """
 from time import sleep
 from . import LSM6DS, LSM6DS_DEFAULT_ADDRESS, GyroRange, RWBit, const
@@ -12,10 +13,37 @@
 
 class ISM330DHCX(LSM6DS):  # pylint: disable=too-many-instance-attributes
 
-    """Driver for the LSM6DS33 6-axis accelerometer and gyroscope.
+    """Driver for the ISM330DHCX 6-axis accelerometer and gyroscope.
+
+    :param ~busio.I2C i2c_bus: The I2C bus the device is connected to.
+    :param int address: The I2C device address. Defaults to :const:`0x6A`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`ISM330DHCX` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_lsm6ds.ism330dhcx import ISM330DHCX
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            sensor = ISM330DHCX(i2c)
+
+        Now you have access to the :attr:`acceleration` and :attr:`gyro`: attributes
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+            gyro_x, gyro_z, gyro_z = sensor.gyro
+
 
-    :param ~busio.I2C i2c_bus: The I2C bus the LSM6DS33 is connected to.
-    :param address: The I2C address of the sensor
     """
 
     CHIP_ID = 0x6B
@@ -40,7 +68,7 @@ def __init__(self, i2c_bus, address=LSM6DS_DEFAULT_ADDRESS):
     @property
     def gyro_range(self):
         """Adjusts the range of values that the sensor can measure, from 125 Degrees/s to 4000
-        degrees/s. Note that larger ranges will be less accurate. Must be a `GyroRange`. 4000 DPS
+        degrees/s. Note that larger ranges will be less accurate. Must be a ``GyroRange``. 4000 DPS
         is only available for the ISM330DHCX"""
         return self._cached_gyro_range
 

diff --git a/adafruit_lsm6ds/lsm6ds33.py b/adafruit_lsm6ds/lsm6ds33.py
@@ -2,7 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-This module provides the LSM6DS33 subclass of LSM6DS for using LSM6DS33 sensors.
+This module provides the `adafruit_lsm6ds.lsm6ds33` subclass of LSM6DS sensors
+===============================================================================
 """
 from . import LSM6DS
 
@@ -12,7 +13,33 @@ class LSM6DS33(LSM6DS):  # pylint: disable=too-many-instance-attributes
     """Driver for the LSM6DS33 6-axis accelerometer and gyroscope.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LSM6DS33 is connected to.
-    :param address: The I2C address of the sensor
+    :param int address: The I2C device address. Defaults to :const:`0x6A`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LSM6DS33` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_lsm6ds.lsm6ds33 import LSM6DS33
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            sensor = LSM6DS33(i2c)
+
+        Now you have access to the :attr:`acceleration` and :attr:`gyro`: attributes
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+            gyro_x, gyro_z, gyro_z = sensor.gyro
+
     """
 
     CHIP_ID = 0x69
diff --git a/adafruit_lsm6ds/lsm6dso32.py b/adafruit_lsm6ds/lsm6dso32.py
@@ -2,7 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-This module provides the LSM6DSO32 subclass of LSM6DS for using LSM6DSO32 sensors.
+This module provides the `adafruit_lsm6ds.lsm6dso32` subclass of LSM6DS sensors
+=================================================================================
 """
 from . import LSM6DS, LSM6DS_CHIP_ID, LSM6DS_DEFAULT_ADDRESS, AccelRange
 
@@ -12,7 +13,34 @@ class LSM6DSO32(LSM6DS):  # pylint: disable=too-many-instance-attributes
     """Driver for the LSM6DSO32 6-axis accelerometer and gyroscope.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LSM6DSO32 is connected to.
-    :param address: The I2C address of the sensor
+    :param address: The I2C device address. Defaults to :const:`0x6A`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LSM6DSO32` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_lsm6ds.lsm6dso32 import LSM6DSO32
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            sensor = LSM6DSO32(i2c)
+
+        Now you have access to the :attr:`acceleration` and :attr:`gyro`: attributes
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+            gyro_x, gyro_z, gyro_z = sensor.gyro
+
+
     """
 
     CHIP_ID = LSM6DS_CHIP_ID

diff --git a/adafruit_lsm6ds/lsm6dsox.py b/adafruit_lsm6ds/lsm6dsox.py
@@ -2,7 +2,8 @@
 #
 # SPDX-License-Identifier: MIT
 """
-This module provides the LSM6DSOX subclass of LSM6DS for using LSM6DSOX sensors.
+This module provides the `adafruit_lsm6ds.lsm6dsox` subclass of LSM6DS sensors
+==============================================================================
 """
 from . import LSM6DS, LSM6DS_DEFAULT_ADDRESS, LSM6DS_CHIP_ID
 
@@ -12,7 +13,33 @@ class LSM6DSOX(LSM6DS):  # pylint: disable=too-many-instance-attributes
     """Driver for the LSM6DSOX 6-axis accelerometer and gyroscope.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LSM6DSOX is connected to.
-    :param address: The I2C address of the sensor
+    :param int address: The I2C device address. Defaults to :const:`0x6A`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LSM6DSOX` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            from adafruit_lsm6ds.lsm6dsox import LSM6DSOX
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            sensor = LSM6DSOX(i2c)
+
+        Now you have access to the :attr:`acceleration` and :attr:`gyro`: attributes
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+            gyro_x, gyro_z, gyro_z = sensor.gyro
+
     """
 
     CHIP_ID = LSM6DS_CHIP_ID

diff --git a/docs/api.rst b/docs/api.rst
@@ -6,3 +6,18 @@
 
 .. automodule:: adafruit_lsm6ds
    :members:
+   :exclude-members: CV, AccelRange, GyroRange, AccelHPF, Rate
+   :member-order: bysource
+
+
+.. automodule:: adafruit_lsm6ds.ism330dhcx
+   :members:
+
+.. automodule:: adafruit_lsm6ds.lsm6ds33
+   :members:
+
+.. automodule:: adafruit_lsm6ds.lsm6dso32
+   :members:
+
+.. automodule:: adafruit_lsm6ds.lsm6dsox
+   :members: