Merge pull request #3 from jposada202020/improving_docs

tannewt · web-flow · commit f8a535778648 · 2021-04-27T10:55:57.000-07:00
improving_docs. No functionality added
diff --git a/README.rst b/README.rst
@@ -59,14 +59,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
     import adafruit_lis331
 
-    i2c = busio.I2C(board.SCL, board.SDA)
+    i2c = board.I2C()  # uses board.SCL and board.SDA
     lis = adafruit_lis331.LIS331(i2c)
 
     while True:
diff --git a/adafruit_lis331.py b/adafruit_lis331.py
@@ -16,16 +16,15 @@
 
 **Hardware:**
 
-* `Adafruit LIS331HH Breakout <https://www.adafruit.com/products/45XX>`_
-* `Adafruit H3LIS331 Breakout <https://www.adafruit.com/products/45XX>`_
+* `Adafruit LIS331HH Breakout <https://www.adafruit.com/products/4626>`_
+* `Adafruit H3LIS331 Breakout <https://www.adafruit.com/products/4627>`_
 
 **Software and Dependencies:**
 
 * Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
- * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
- * Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
+  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
 """
 
 __version__ = "0.0.0-auto.0"
@@ -61,12 +60,16 @@ class ROByteArray:
     Values are FixNums that map to the values in the defined struct.  See struct
     module documentation for struct format string and its possible value types.
 
-    .. note:: This assumes the device addresses correspond to 8-bit bytes. This is not suitable for
-      devices with registers of other widths such as 16-bit.
+    .. note::
+        This assumes the device addresses correspond to 8-bit bytes.
+        This is not suitable for devices with registers of other
+        widths such as 16-bit.
 
     :param int register_address: The register address to begin reading the array from
-    :param str struct_format: The struct format string for this register.
+    :param str format_str: The struct format string for this register.
     :param int count: Number of elements in the array
+
+
     """
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -203,7 +206,7 @@ class LIS331:
     **Cannot be instantiated directly**
 
         :param ~busio.I2C i2c_bus: The I2C bus the LIS331 is connected to.
-        :param address: The I2C slave address of the sensor
+        :param address: The I2C device address.  Defaults to :const:`0x18`
 
     """
 
@@ -261,6 +264,7 @@ def hpf_reference(self):
         is a signed 8-bit number from -128 to 127. The value of each increment of 1 depends on the
         currently set measurement range and is approximate:
         #pylint: disable=line-too-long
+
         +-------------------------------------------------------------+-------------------------------+
         | Range                                                       | Incremental value (LSB value) |
         +-------------------------------------------------------------+-------------------------------+
@@ -270,6 +274,7 @@ def hpf_reference(self):
         +-------------------------------------------------------------+-------------------------------+
         | ``LIS331HHRange.RANGE_24G`` or ``H3LIS331Range.RANGE_400G`` | ~63mg                         |
         +-------------------------------------------------------------+-------------------------------+
+
         #pylint: enable=line-too-long
         """
 
@@ -282,9 +287,10 @@ def hpf_reference(self, reference_value):
         self._reference_value = reference_value
 
     def zero_hpf(self):
-        """When the high-pass filter is enabled  with ``use_reference=False``, calling ``zero_hpf``
-        will set all measurements to zero immediately, avoiding the normal settling time seen when
-        using the high-pass filter without a ``hpf_reference``
+        """When the high-pass filter is enabled  with ``use_reference=False``,
+        calling :meth:`zero_hpf` will set all measurements to zero immediately,
+        avoiding the normal settling time seen when using the high-pass filter
+        without a :meth:`hpf_reference`
         """
         self._zero_hpf  # pylint: disable=pointless-statement
 
@@ -294,12 +300,14 @@ def enable_hpf(
         """Enable or disable the high-pass filter.
 
         :param enabled: Enable or disable the filter. Default is `True` to enable
-        :param ~RateDivisor cutoff: A `RateDivisor` to set the high-pass cutoff frequency. Default\
-        is ``RateDivisor.ODR_DIV_50``. See ``RateDivisor`` for more information
+        :param ``RateDivisor`` cutoff: A ``RateDivisor`` to set the high-pass
+         cutoff frequency. Default is ``RateDivisor.ODR_DIV_50``. See ``RateDivisor``
+         for more information
         :param use_reference: Determines if the filtered measurements are offset by a reference\
-        value. Default is false.
+         value. Default is false.
 
-    See section **4** of the LIS331DLH application note for more information `LIS331DLH application\
+        See section **4** of the LIS331DLH application note for more information
+        `LIS331DLH application
         note for more information <https://www.st.com/content/ccc/resource/technical/document/\
         application_note/b5/8e/58/69/cb/87/45/55/CD00215823.pdf/files/CD00215823.pdf/jcr:content/\
         translations/en.CD00215823.pdf>`_
@@ -311,7 +319,7 @@ def enable_hpf(
 
     @property
     def 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._cached_data_rate
 
     @data_rate.setter
@@ -330,8 +338,8 @@ def data_rate(self, new_rate_bits):
 
     @property
     def mode(self):
-        """The `Mode` power mode that the sensor is set to, as determined by the current
-        `data_rate`. To set the mode, use `data_rate` and the approprite `Rate`"""
+        """The :attr:`Mode` power mode that the sensor is set to, as determined by the current
+        `data_rate`. To set the mode, use `data_rate` and the appropriate ``Rate``"""
         mode_bits = self._mode_and_rate()[0]
         return mode_bits
 
@@ -348,7 +356,7 @@ def _mode_and_rate(self, data_rate=None):
     @property
     def range(self):
         """Adjusts the range of values that the sensor can measure, Note that larger ranges will be
-        less accurate. Must be a `H3LIS331Range` or `LIS331HHRange`"""
+        less accurate. Must be a ``H3LIS331Range`` or ``LIS331HHRange``"""
         return self._range_bits
 
     @range.setter
@@ -363,7 +371,7 @@ def range(self, new_range):
 
     @property
     def acceleration(self):
-        """The x, y, z acceleration values returned in a 3-tuple and are in m / s ^ 2."""
+        """The x, y, z acceleration values returned in a 3-tuple and are in :math:`m / s ^ 2`."""
 
         raw_acceleration_bytes = self._raw_acceleration
 
@@ -385,7 +393,30 @@ class LIS331HH(LIS331):
     """Driver for the LIS331HH 3-axis high-g accelerometer.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LIS331 is connected to.
-    :param address: The I2C slave address of the sensor
+    :param address: The I2C device address. Defaults to :const:`0x18`
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LIS331` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_lis331
+
+        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
+            lis = adafruit_lis331.LIS331HH(i2c)
+
+        Now you have access to the :attr:`acceleration` attribute
+
+        .. code-block:: python
+
+            acceleration = lis.acceleration
 
     """
 
@@ -401,7 +432,32 @@ class H3LIS331(LIS331):
     """Driver for the H3LIS331 3-axis high-g accelerometer.
 
     :param ~busio.I2C i2c_bus: The I2C bus the LIS331 is connected to.
-    :param address: The I2C slave address of the sensor
+    :param address: The I2C slave address of the sensor. Defaults to :const:`0x18`
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LIS331` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_lis331
+
+        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
+            lis = adafruit_lis331.H3LIS331(i2c)
+
+        Now you have access to the :attr:`acceleration` attribute
+
+        .. code-block:: python
+
+            acceleration = lis.acceleration
+
+
 
     """
 
diff --git a/docs/api.rst b/docs/api.rst
@@ -6,3 +6,5 @@
 
 .. automodule:: adafruit_lis331
    :members:
+   :exclude-members: ROByteArray, CV, RateDivisor, Frequency, Mode, Rate, H3LIS331Range, LIS331HHRange
+   :member-order: bysource
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -6,3 +6,21 @@ Ensure your device works with this simple test.
 .. literalinclude:: ../examples/lis331_simpletest.py
     :caption: examples/lis331_simpletest.py
     :linenos:
+
+Low Pass Filter
+---------------
+
+Example showing a low pass filter example
+
+.. literalinclude:: ../examples/lis331_low_pass_filter.py
+    :caption: examples/lis331_low_pass_filter.py
+    :linenos:
+
+High Pass Filter
+----------------
+
+Example showing a high pass filter example
+
+.. literalinclude:: ../examples/lis331_high_pass_filter.py
+    :caption: examples/lis331_high_pass_filter.py
+    :linenos:
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,7 +23,7 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-
+    Adafruit LIS331HH 3-axis Accelerometer Breakout Learning Guide <https://learn.adafruit.com/adafruit-h3lis331-and-lis331hh-high-g-3-axis-accelerometers/overview>
 
 .. toctree::
     :caption: Related Products
diff --git a/examples/lis331_high_pass_filter.py b/examples/lis331_high_pass_filter.py
@@ -3,10 +3,9 @@
 
 import time
 import board
-import busio
 import adafruit_lis331
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 # un-comment the sensor you are using
 # lis = H3LIS331(i2c)
 lis = adafruit_lis331.LIS331HH(i2c)
diff --git a/examples/lis331_low_pass_filter.py b/examples/lis331_low_pass_filter.py
@@ -3,10 +3,9 @@
 
 import time
 import board
-import busio
 from adafruit_lis331 import LIS331HH, Rate, Frequency
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 
 # un-comment the sensor you are using
 # lis = H3LIS331(i2c)
diff --git a/examples/lis331_simpletest.py b/examples/lis331_simpletest.py
@@ -3,10 +3,9 @@
 
 import time
 import board
-import busio
 import adafruit_lis331
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 lis = adafruit_lis331.LIS331HH(i2c)
 
 while True:
