Improve Ref Docs

.travis.yml

@@ -16,15 +16,17 @@ deploy:
   provider: releases
   api_key: $GITHUB_TOKEN
   file_glob: true
-  file: bundles/*
+  file: $TRAVIS_BUILD_DIR/bundles/*
   skip_cleanup: true
+  overwrite: true
   on:
     tags: true
 
 install:
-  - pip install pylint circuitpython-build-tools
+  - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
 
 script:
   - pylint adafruit_lis3dh.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-lis3dh --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

README.rst

@@ -14,26 +14,22 @@ Adafruit CircuitPython module for the LIS3DH accelerometer.
 
 Note this module is made to work with CircuitPython and not MicroPython APIs.
 
+Usage Example
+=============
+
 See the guide at: https://learn.adafruit.com/circuitpython-hardware-lis3dh-accelerometer
 
 Dependencies
 =============
 This driver depends on:
 
 * `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
 
 Please ensure all dependencies are available on the CircuitPython filesystem.
 This is easily achieved by downloading
 `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 
-API Reference
-=============
-
-.. toctree::
-   :maxdepth: 2
-
-   api
-
 Contributing
 ============
 
@@ -64,3 +60,26 @@ Then run the build:
 .. code-block::shell
 
     circuitpython-build-bundles --filename_prefix adafruit-circuitpython-lis3dh --library_location .
+
+Sphinx documentation
+-----------------------
+
+Sphinx is used to build the documentation based on rST files and comments in the code. First,
+install dependencies (feel free to reuse the virtual environment from above):
+
+.. code-block:: shell
+
+    python3 -m venv .env
+    source .env/bin/activate
+    pip install Sphinx sphinx-rtd-theme
+
+Now, once you have the virtual environment activated:
+
+.. code-block:: shell
+
+    cd docs
+    sphinx-build -E -W -b html . _build/html
+
+This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
+view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
+locally verify it will pass.

adafruit_lis3dh.py

@@ -12,6 +12,22 @@
 See examples in the examples directory.
 
 * Author(s): Tony DiCola
+
+Implementation Notes
+--------------------
+
+**Hardware:**
+
+* `Adafruit LIS3DH Triple-Axis Accelerometer Breakout
+  <https://www.adafruit.com/product/2809>`_
+
+* `Circuit Playground Express <https://www.adafruit.com/product/3333>`_
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
+  https://github.com/adafruit/circuitpython/releases
+* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 """
 
 import time
@@ -149,16 +165,20 @@ def acceleration(self):
         return x, y, z
 
     def shake(self, shake_threshold=30, avg_count=10, total_delay=0.1):
-        """Detect when the accelerometer is shaken. Optional parameters:
-         shake_threshold - Increase or decrease to change shake sensitivity. This
-                           requires a minimum value of 10. 10 is the total
-                           acceleration if the board is not moving, therefore
-                           anything less than 10 will erroneously report a constant
-                           shake detected. (Default 30)
-         avg_count - The number of readings taken and used for the average
-                     acceleration. (Default 10)
-         total_delay - The total time in seconds it takes to obtain avg_count
-                       readings from acceleration. (Default 0.1)
+        """
+        Detect when the accelerometer is shaken. Optional parameters:
+
+        :param shake_threshold: Increase or decrease to change shake sensitivity. This
+                                requires a minimum value of 10. 10 is the total
+                                acceleration if the board is not moving, therefore
+                                anything less than 10 will erroneously report a constant
+                                shake detected. (Default 30)
+
+        :param avg_count: The number of readings taken and used for the average
+                          acceleration. (Default 10)
+
+        :param total_delay: The total time in seconds it takes to obtain avg_count
+                            readings from acceleration. (Default 0.1)
          """
         shake_accel = (0, 0, 0)
         for _ in range(avg_count):
@@ -204,45 +224,50 @@ def read_adc_mV(self, adc): # pylint: disable=invalid-name
 
     @property
     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
-           multiple reads even if only a single tap or single double tap occurred if the
-           interrupt (int) pin is not specified.
+        """
+        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
+        multiple reads even if only a single tap or single double tap occurred if the
+        interrupt (int) pin is not specified.
 
-           The following example uses ``i2c`` and specifies the interrupt pin:
+        The following example uses ``i2c`` and specifies the interrupt pin:
 
-           .. code-block:: python
+        .. code-block:: python
 
-             import adafruit_lis3dh
-             import digitalio
+            import adafruit_lis3dh
+            import digitalio
 
-             i2c = busio.I2C(board.SCL, board.SDA)
-             int1 = digitalio.DigitalInOut(board.D11) # pin connected to interrupt
-             lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, int1=int1)
-             lis3dh.range = adafruit_lis3dh.RANGE_8_G
+            i2c = busio.I2C(board.SCL, board.SDA)
+            int1 = digitalio.DigitalInOut(board.D11) # pin connected to interrupt
+            lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, int1=int1)
+            lis3dh.range = adafruit_lis3dh.RANGE_8_G
 
-           """
+        """
         if self._int1 and not self._int1.value:
             return False
         raw = self._read_register_byte(REG_CLICKSRC)
         return raw & 0x40 > 0
 
     def set_tap(self, tap, threshold, *,
                 time_limit=10, time_latency=20, time_window=255, click_cfg=None):
-        """Set the tap detection parameters.
-
-           .. note:: Tap related registers are called CLICK_ in the datasheet.
-
-            :param int tap: 0 to disable tap detection, 1 to detect only single
-              taps, and 2 to detect only double taps.
-            :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."""
+        """
+        Set the tap detection parameters.
+
+        .. note:: Tap related registers are called ``CLICK_`` in the datasheet.
+
+        :param int tap: 0 to disable tap detection, 1 to detect only single
+                        taps, and 2 to detect only double taps.
+
+        :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.
+        """
         if (tap < 0 or tap > 2) and click_cfg is None:
             raise ValueError('Tap must be 0 (disabled), 1 (single tap), or 2 (double tap)!')
         if threshold > 127 or threshold < 0:

api.rst → docs/api.rst

@@ -1,5 +1,5 @@
 
 .. If you created a package, create one automodule per module in the package.
 
-.. automodule:: adafruit_lis3dh.lis3dh
+.. automodule:: adafruit_lis3dh
    :members:

conf.py → docs/conf.py

@@ -2,7 +2,7 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -28,7 +28,7 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'README'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Adafruit VL53L0X Library'
@@ -54,7 +54,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -71,6 +71,9 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# If this is True, todo emits a warning for each TODO entries. The default is False.
+todo_emit_warnings = True
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -95,6 +98,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+html_favicon = '_static/favicon.ico'
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'AdafruitVL53L0XLibrarydoc'
 

docs/examples.rst

@@ -0,0 +1,22 @@
+Simple test
+------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/accel.py
+    :caption: examples/accel.py
+    :linenos:
+
+Here are some additional examples:
+
+.. literalinclude:: ../examples/tap.py
+    :caption: examples/tap.py
+    :linenos:
+
+.. literalinclude:: ../examples/adc.py
+    :caption: examples/adc.py
+    :linenos:
+
+.. literalinclude:: ../examples/spinner.py
+    :caption: examples/spinner.py
+    :linenos:

docs/index.rst

@@ -0,0 +1,49 @@
+.. include:: ../README.rst
+
+Table of Contents
+=================
+
+.. toctree::
+    :maxdepth: 4
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: Examples
+
+    examples
+
+.. toctree::
+    :caption: API Reference
+    :maxdepth: 3
+
+    api
+
+.. toctree::
+    :caption: Tutorials
+
+.. toctree::
+    :caption: Related Products
+
+    Adafruit LIS3DH Triple-Axis Accelerometer Breakout <https://www.adafruit.com/product/2809>
+
+    Circuit Playground Express <https://www.adafruit.com/product/3333>
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_LIS3DH/releases/latest>
+    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
+    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
+    Discord Chat <https://adafru.it/discord>
+    Adafruit Learning System <https://learn.adafruit.com>
+    Adafruit Blog <https://blog.adafruit.com>
+    Adafruit Store <https://www.adafruit.com>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`