Merge pull request #11 from jposada202020/improving_docs

improving_docs

Author: kattni

README.rst

@@ -56,14 +56,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_lsm303_accel
 
-        i2c = busio.I2C(board.SCL, board.SDA)
+        i2c = board.I2C()  # uses board.SCL and board.SDA
         sensor = adafruit_lsm303_accel.LSM303_Accel(i2c)
 
         while True:

adafruit_lsm303_accel.py

@@ -23,7 +23,7 @@
 
 **Software and Dependencies:**
 
-* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
+* Adafruit CircuitPython firmware for the supported boards:
   https://circuitpython.org/downloads
 * Adafruit's Bus Device library:
   https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
@@ -124,7 +124,36 @@ class Range:
 
 
 class LSM303_Accel:  # pylint:disable=too-many-instance-attributes
-    """Driver for the LSM303's accelerometer."""
+    """Driver for the LSM303's accelerometer.
+
+    :param ~busio.I2C i2c: The I2C bus the device is connected to.
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`LSM303_Accel` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_lsm303_accel
+
+        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 = adafruit_lsm303_accel.LSM303_Accel(i2c)
+
+        Now you have access to the :attr:`acceleration` attribute
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+
+
+    """
 
     # Class-level buffer for reading and writing data with the sensor.
     # This reduces memory allocations but means the code is not re-entrant or
@@ -141,22 +170,7 @@ class LSM303_Accel:  # pylint:disable=too-many-instance-attributes
 
     _act_threshold = UnaryStruct(_REG_ACCEL_ACT_THS_A, "B")
     _act_duration = UnaryStruct(_REG_ACCEL_ACT_DUR_A, "B")
-    """
-    .. code-block:: python
-
-        import board
-        i2c = board.I2C()
-
-        import adafruit_lsm303_accel
-        accel = adafruit_lsm303_accel.LSM303_Accel(i2c)
 
-        accel._act_threshold = 20
-        accel._act_duration = 1
-        accel._int2_activity_enable = True
-
-        # toggle pins, defaults to False
-        accel._int_pin_active_low = True
-    """
     _data_rate = RWBits(4, _REG_ACCEL_CTRL_REG1_A, 4)
     _enable_xyz = RWBits(3, _REG_ACCEL_CTRL_REG1_A, 0)
     _raw_accel_data = StructArray(_REG_ACCEL_OUT_X_L_A, "<h", 3)
@@ -211,10 +225,10 @@ def set_tap(
         :param int threshold: A threshold for the tap detection.  The higher the value the less\
             sensitive the detection. This changes based on the accelerometer range.  Good values\
             are 5-10 for 16G, 10-20 for 8G, 20-40 for 4G, and 40-80 for 2G.
-        :param int time_limit: TIME_LIMIT register value (default 10).
-        :param int time_latency: TIME_LATENCY register value (default 20).
-        :param int time_window: TIME_WINDOW register value (default 255).
-        :param int click_cfg: CLICK_CFG register value.
+        :param int time_limit: TIME_LIMIT register value. Defaults to :const:`10`
+        :param int time_latency: TIME_LATENCY register value. Defaults to :const:`20`
+        :param int time_window: TIME_WINDOW register value. Defaults to :const:`255`
+        :param int tap_cfg: CLICK_CFG register value. Defaults to `None`
 
         """
 
@@ -250,7 +264,7 @@ def set_tap(
     def tapped(self):
         """
         True if a tap was detected recently. Whether its a single tap or double tap is
-        determined by the tap param on ``set_tap``. ``tapped`` may be True over
+        determined by the tap param on :meth:`set_tap`. :attr:`tapped` may be True over
         multiple reads even if only a single tap or single double tap occurred.
         """
         tap_src = self._tap_src

docs/examples.rst

@@ -7,6 +7,31 @@ Ensure your device works with these simple tests.
     :caption: examples/lsm303_simpletest.py
     :linenos:
 
+Fast Acceleration Example
+-------------------------
+
+Example to demonstrate fast acceleration data acquisition
+
 .. literalinclude:: ../examples/lsm303_accel_fast.py
     :caption: examples/lsm303_fast_accel.py
     :linenos:
+
+
+Inclinometer Example
+-------------------------
+
+Demonstrate inclinometer example
+
+.. literalinclude:: ../examples/lsm303_accel_inclinometer.py
+    :caption: examples/lsm303_accel_inclinometer.py
+    :linenos:
+
+
+Tap Detection Example
+-------------------------
+
+Tap detection example
+
+.. literalinclude:: ../examples/lsm303_accel_tap_detection.py
+    :caption: examples/lsm303_accel_tap_detection.py
+    :linenos:

docs/index.rst

@@ -23,6 +23,10 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Triple-axis Accelerometer+Magnetometer (Compass) Board - LSM303 Learning Guide <https://learn.adafruit.com/lsm303-accelerometer-slash-compass-breakout>
+
+    FLORA Accelerometer/Compass Sensor - LSM303 Learning Guide <https://learn.adafruit.com/flora-accelerometer/>
+
 .. toctree::
     :caption: Related Products
 

examples/lsm303_accel_fast.py

@@ -4,12 +4,11 @@
 """ Read data from the accelerometer and print it out, ASAP! """
 
 import board
-import busio
-
 import adafruit_lsm303_accel
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 sensor = adafruit_lsm303_accel.LSM303_Accel(i2c)
+
 while True:
     accel_x, accel_y, accel_z = sensor.acceleration
     print("{0:10.3f} {1:10.3f} {2:10.3f}".format(accel_x, accel_y, accel_z))

examples/lsm303_accel_inclinometer.py

@@ -6,11 +6,10 @@
 import time
 from math import atan2, degrees
 import board
-import busio
 import adafruit_lsm303_accel
 
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 sensor = adafruit_lsm303_accel.LSM303_Accel(i2c)
 
 

examples/lsm303_accel_simpletest.py

@@ -5,10 +5,9 @@
 
 import time
 import board
-import busio
 import adafruit_lsm303_accel
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 sensor = adafruit_lsm303_accel.LSM303_Accel(i2c)
 
 while True:

examples/lsm303_accel_tap_detection.py

@@ -2,10 +2,9 @@
 # SPDX-License-Identifier: MIT
 
 import board
-import busio
 import adafruit_lsm303_accel
 
-i2c = busio.I2C(board.SCL, board.SDA)
+i2c = board.I2C()  # uses board.SCL and board.SDA
 accel = adafruit_lsm303_accel.LSM303_Accel(i2c)
 accel.range = adafruit_lsm303_accel.Range.RANGE_8G
 accel.set_tap(1, 30)