From d263845a60951ac04bca3e4c4c1b19ec892096d8 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Tue, 27 Feb 2018 23:41:31 -0600 Subject: [PATCH 01/10] setup docs fodlers --- docs/_static/favicon.ico | Bin 0 -> 4414 bytes api.rst => docs/api.rst | 0 conf.py => docs/conf.py | 15 +++++++++--- docs/examples.rst | 22 ++++++++++++++++++ docs/index.rst | 49 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 83 insertions(+), 3 deletions(-) create mode 100644 docs/_static/favicon.ico rename api.rst => docs/api.rst (100%) rename conf.py => docs/conf.py (90%) create mode 100644 docs/examples.rst create mode 100644 docs/index.rst diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..5aca98376a1f7e593ebd9cf41a808512c2135635 GIT binary patch literal 4414 zcmd^BX;4#F6n=SG-XmlONeGrD5E6J{RVh+e928U#MG!$jWvO+UsvWh`x&VqGNx*en zx=qox7Dqv{kPwo%fZC$dDwVpRtz{HzTkSs8QhG0)%Y=-3@Kt!4ag|JcIo?$-F|?bXVS9UDUyev>MVZQ(H8K4#;BQW-t2CPorj8^KJrMX}QK zp+e<;4ldpXz~=)2GxNy811&)gt-}Q*yVQpsxr@VMoA##{)$1~=bZ1MmjeFw?uT(`8 z^g=09<=zW%r%buwN%iHtuKSg|+r7HkT0PYN*_u9k1;^Ss-Z!RBfJ?Un4w(awqp2b3 z%+myoFis_lTlCrGx2z$0BQdh+7?!JK#9K9@Z!VrG zNj6gK5r(b4?YDOLw|DPRoN7bdP{(>GEG41YcN~4r_SUHU2hgVtUwZG@s%edC;k7Sn zC)RvEnlq~raE2mY2ko64^m1KQL}3riixh?#J{o)IT+K-RdHae2eRX91-+g!y`8^># z-zI0ir>P%Xon)!@xp-BK2bDYUB9k613NRrY6%lVjbFcQc*pRqiK~8xtkNPLxt}e?&QsTB}^!39t_%Qb)~Ukn0O%iC;zt z<&A-y;3h++)>c1br`5VFM~5(83!HKx$L+my8sW_c#@x*|*vB1yU)_dt3vH;2hqPWx zAl^6@?ipx&U7pf`a*>Yq6C85nb+B=Fnn+(id$W#WB^uHAcZVG`qg;rWB}ubvi(Y>D z$ei>REw$#xp0SHAd^|1hq&9HJ=jKK8^zTH~nk)G?yUcmTh9vUM6Y0LMw4(gYVY$D$ zGl&WY&H<)BbJ&3sYbKjx1j^=3-0Q#f^}(aP1?8^`&FUWMp|rmtpK)bLQ1Zo?^s4jqK=Lfg*9&geMGVQ z#^-*!V`fG@;H&{M9S8%+;|h&Qrxym0Ar>WT4BCVLR8cGXF=JmEYN(sNT(9vl+S|%g z8r7nXQ(95i^`=+XHo|){$vf2$?=`F$^&wFlYXyXg$B{a>$-Fp+V}+D;9k=~Xl~?C4 zAB-;RKXdUzBJE{V&d&%R>aEfFe;vxqI$0@hwVM}gFeQR@j}a>DDxR+n+-*6|_)k%% z*mSpDV|=5I9!&VC&9tD%fcVygWZV!iIo2qFtm#!*(s|@ZT33*Ad;+<|3^+yrp*;oH zBSYLV(H1zTU?2WjrCQoQW)Z>J2a=dTriuvezBmu16`tM2fm7Q@d4^iqII-xFpwHGI zn9CL}QE*1vdj2PX{PIuqOe5dracsciH6OlAZATvE8rj6ykqdIjal2 z0S0S~PwHb-5?OQ-tU-^KTG@XNrEVSvo|HIP?H;7ZhYeZkhSqh-{reE!5di;1zk$#Y zCe7rOnlzFYJ6Z#Hm$GoidKB=2HBCwm`BbZVeZY4ukmG%1uz7p2URs6c9j-Gjj^oQV zsdDb3@k2e`C$1I5ML5U0Qs0C1GAp^?!*`=|Nm(vWz3j*j*8ucum2;r0^-6Aca=Gv) zc%}&;!+_*S2tlnnJnz0EKeRmw-Y!@9ob!XQBwiv}^u9MkaXHvM=!<3YX;+2#5Cj5pp?FEK750S3BgeSDtaE^ zXUM@xoV6yBFKfzvY20V&Lr0yC + + 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` From 98e0b3317f890cc3fb8bf4bc06b53cbddc67a3a2 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Tue, 27 Feb 2018 23:43:01 -0600 Subject: [PATCH 02/10] updated .travis & .readthedocs yml --- readthedocs.yml => .readthedocs.yml | 0 .travis.yml | 6 ++++-- 2 files changed, 4 insertions(+), 2 deletions(-) rename readthedocs.yml => .readthedocs.yml (100%) 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 From 778c0e086aeae6a8ca1d5ab2804904ccad444156 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Tue, 27 Feb 2018 23:45:06 -0600 Subject: [PATCH 03/10] updated README --- README.rst | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) 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. From 23ccabc80b1d0c6969d3bf273525d60971249592 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Tue, 27 Feb 2018 23:48:16 -0600 Subject: [PATCH 04/10] added info to docstring --- adafruit_lis3dh.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index 2de8410..3354e36 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 From 9ec4334cc9c6cca50a06f756e1b4c6848963c4e0 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Tue, 27 Feb 2018 23:52:53 -0600 Subject: [PATCH 05/10] updated api; ref'd nested module --- docs/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 0a1245e..878653f 100644 --- a/docs/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: From 94b454d5e74062d0db53ebc3941043fb4b03c8c4 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Wed, 28 Feb 2018 00:04:21 -0600 Subject: [PATCH 06/10] sphinx fixes; docstring formatting --- adafruit_lis3dh.py | 78 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index 3354e36..90a6dfa 100755 --- a/adafruit_lis3dh.py +++ b/adafruit_lis3dh.py @@ -165,16 +165,17 @@ 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): @@ -220,24 +221,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) @@ -245,20 +247,22 @@ 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.""" + """ + 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: From 2b4242e4a9568e218fd60b4052a5d553d363ed6f Mon Sep 17 00:00:00 2001 From: sommersoft Date: Wed, 28 Feb 2018 00:09:35 -0600 Subject: [PATCH 07/10] sphinx fixes; docstring formatting2 --- adafruit_lis3dh.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index 90a6dfa..bc90d2a 100755 --- a/adafruit_lis3dh.py +++ b/adafruit_lis3dh.py @@ -167,13 +167,16 @@ def acceleration(self): def shake(self, shake_threshold=30, avg_count=10, total_delay=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) """ @@ -254,10 +257,12 @@ def set_tap(self, tap, threshold, *, :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). From 30cd8693fd3fef314f5c2b68bb2a47dab87ffff2 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Wed, 28 Feb 2018 00:14:52 -0600 Subject: [PATCH 08/10] sphinx fix; unknown target 'click' --- adafruit_lis3dh.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index bc90d2a..0bb561f 100755 --- a/adafruit_lis3dh.py +++ b/adafruit_lis3dh.py @@ -253,7 +253,7 @@ def set_tap(self, tap, threshold, *, """ Set the tap detection parameters. - .. note:: Tap related registers are called CLICK_ in the datasheet. + .. 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. From 0eebb5e5fb209fa6594959a24c5541b2732c45c2 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Wed, 28 Feb 2018 20:02:34 -0600 Subject: [PATCH 09/10] docstring fix --- adafruit_lis3dh.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adafruit_lis3dh.py b/adafruit_lis3dh.py index 0bb561f..888c89f 100755 --- a/adafruit_lis3dh.py +++ b/adafruit_lis3dh.py @@ -251,7 +251,7 @@ 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. + The tap detection parameters. .. note:: Tap related registers are called ``CLICK_`` in the datasheet. From a051c2df30ee127af442dc384f78bbe0748923d0 Mon Sep 17 00:00:00 2001 From: sommersoft Date: Wed, 28 Feb 2018 20:04:09 -0600 Subject: [PATCH 10/10] renamed accel example; updated RTD example --- docs/examples.rst | 4 ++-- examples/{accel.py => lis3dh_simpletest.py} | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename examples/{accel.py => lis3dh_simpletest.py} (100%) diff --git a/docs/examples.rst b/docs/examples.rst index f3490a7..cd392e5 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -3,8 +3,8 @@ Simple test Ensure your device works with this simple test. -.. literalinclude:: ../examples/accel.py - :caption: examples/accel.py +.. literalinclude:: ../examples/lis3dh_simpletest.py + :caption: examples/lis3dh_simpletest.py :linenos: Here are some additional examples: 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