diff --git a/readthedocs.yml b/.readthedocs.yml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yml diff --git a/.travis.yml b/.travis.yml index ae17fd9..721b737 100644 --- a/.travis.yml +++ b/.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 diff --git a/README.rst b/README.rst index a2b5c63..909c751 100644 --- a/README.rst +++ b/README.rst @@ -14,6 +14,9 @@ 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 @@ -21,19 +24,12 @@ Dependencies This driver depends on: * `Adafruit CircuitPython `_ +* `Bus Device `_ Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading `the Adafruit library and driver 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. diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index 2de8410..888c89f 100755 --- a/adafruit_lis3dh.py +++ b/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 + `_ + +* `Circuit Playground Express `_ + +**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,24 +224,25 @@ 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) @@ -229,20 +250,24 @@ def tapped(self): 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.""" + """ + 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: diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000..5aca983 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/api.rst b/docs/api.rst similarity index 70% rename from api.rst rename to docs/api.rst index 0a1245e..878653f 100644 --- a/api.rst +++ b/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: diff --git a/conf.py b/docs/conf.py similarity index 90% rename from conf.py rename to docs/conf.py index 9290fed..2196989 100644 --- a/conf.py +++ b/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' diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..cd392e5 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,22 @@ +Simple test +------------ + +Ensure your device works with this simple test. + +.. literalinclude:: ../examples/lis3dh_simpletest.py + :caption: examples/lis3dh_simpletest.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: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..a02511d --- /dev/null +++ b/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 + + Circuit Playground Express + +.. toctree:: + :caption: Other Links + + Download + CircuitPython Reference Documentation + CircuitPython Support Forum + Discord Chat + Adafruit Learning System + Adafruit Blog + Adafruit Store + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/examples/accel.py b/examples/lis3dh_simpletest.py similarity index 100% rename from examples/accel.py rename to examples/lis3dh_simpletest.py