Merge pull request #17 from jposada202020/improving_docs

improving_docs

Author: kattni

adafruit_mma8451.py

@@ -10,6 +10,23 @@
 examples/simpletest.py for a demo of the usage.
 
 * Author(s): Tony DiCola
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+* Adafruit `Triple-Axis Accelerometer - ±2/4/8g @ 14-bit - MMA8451
+  <https://www.adafruit.com/product/2019>`_
+
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
+* Adafruit's Bus Device library:
+  https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+
 """
 try:
     import struct
@@ -64,10 +81,35 @@
 
 class MMA8451:
     """MMA8451 accelerometer.  Create an instance by specifying:
-    - i2c: The I2C bus connected to the sensor.
 
-    Optionally specify:
-    - address: The I2C address of the sensor if not the default of 0x1D.
+    :param ~busio.I2C i2c: The I2C bus the device is connected to.
+    :param int address: The I2C device address. Defaults to :const:`0x1D`
+
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`MMA8451` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import board
+            import adafruit_mma8451
+
+        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_mma8451.MMA8451(i2c)
+
+        Now you have access to the :attr:`acceleration` and :attr:`orientation` attributes
+
+        .. code-block:: python
+
+            acc_x, acc_y, acc_z = sensor.acceleration
+            orientation = sensor.orientation
+
     """
 
     # Class-level buffer to reduce allocations and fragmentation.
@@ -124,9 +166,11 @@ def _write_u8(self, address, val):
     @property
     def range(self):
         """Get and set the range of the sensor.  Must be a value of:
+
         - RANGE_8G: +/- 8g
         - RANGE_4G: +/- 4g (the default)
         - RANGE_2G: +/- 2g
+
         """
         return self._read_u8(_MMA8451_REG_XYZ_DATA_CFG) & 0x03
 
@@ -141,6 +185,7 @@ def range(self, val):
     @property
     def data_rate(self):
         """Get and set the data rate of the sensor.  Must be a value of:
+
         - DATARATE_800HZ:   800Hz (the default)
         - DATARATE_400HZ:   400Hz
         - DATARATE_200HZ:   200Hz
@@ -149,6 +194,7 @@ def data_rate(self):
         - DATARATE_12_5HZ: 12.5Hz
         - DATARATE_6_25HZ: 6.25Hz
         - DATARATE_1_56HZ: 1.56Hz
+
         """
         return (self._read_u8(_MMA8451_REG_CTRL_REG1) >> 3) & _MMA8451_DATARATE_MASK
 
@@ -166,7 +212,7 @@ def acceleration(self):
         # pylint: disable=no-else-return
         # This needs to be refactored when it can be tested
         """Get the acceleration measured by the sensor.  Will return a 3-tuple
-        of X, Y, Z axis acceleration values in m/s^2.
+        of X, Y, Z axis acceleration values in :math:`m/s^2`.
         """
         # Read 6 bytes for 16-bit X, Y, Z values.
         self._read_into(_MMA8451_REG_OUT_X_MSB, self._BUFFER, count=6)
@@ -201,6 +247,7 @@ def acceleration(self):
     @property
     def orientation(self):
         """Get the orientation of the MMA8451.  Will return a value of:
+
         - PL_PUF: Portrait, up, front
         - PL_PUB: Portrait, up, back
         - PL_PDF: Portrait, down, front
@@ -209,5 +256,6 @@ def orientation(self):
         - PL_LRB: Landscape, right, back
         - PL_LLF: Landscape, left, front
         - PL_LLB: Landscape, left, back
+
         """
         return self._read_u8(_MMA8451_REG_PL_STATUS) & 0x07

docs/index.rst

@@ -23,9 +23,12 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Adafruit Triple-Axis Accelerometer - ±2/4/8g @ 14-bit - MMA8451 Learning Guide <https://learn.adafruit.com/adafruit-mma8451-accelerometer-breakout/>
+
 .. toctree::
     :caption: Related Products
 
+    Adafruit Triple-Axis Accelerometer - ±2/4/8g @ 14-bit - MMA8451 <https://www.adafruit.com/product/2019>
 
 .. toctree::
     :caption: Other Links

examples/mma8451_simpletest.py

@@ -4,15 +4,12 @@
 # Simple demo of reading the MMA8451 orientation every second.
 
 import time
-
 import board
-import busio
-
 import adafruit_mma8451
 
 
-# Initialize I2C bus.
-i2c = busio.I2C(board.SCL, board.SDA)
+# Create sensor object, communicating over the board's default I2C bus
+i2c = board.I2C()  # uses board.SCL and board.SDA
 
 # Initialize MMA8451 module.
 sensor = adafruit_mma8451.MMA8451(i2c)