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 8084f64..dd88629 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,15 +16,16 @@ deploy: provider: releases api_key: $GITHUB_TOKEN file_glob: true - file: bundles/* + file: $TRAVIS_BUILD_DIR/bundles/* skip_cleanup: true on: tags: true install: - - pip install pylint circuitpython-build-tools + - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme script: - pylint adafruit_circuitplayground/*.py - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py) - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-circuitplayground --library_location . + - cd docs && sphinx-build -E -W -b html . _build/html diff --git a/README.rst b/README.rst index e3a0220..6693199 100644 --- a/README.rst +++ b/README.rst @@ -6,10 +6,6 @@ Introduction :target: https://circuitpython.readthedocs.io/projects/circuitplayground/en/latest/ :alt: Documentation Status -.. image :: https://badges.gitter.im/adafruit/circuitpython.svg - :target: https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - :alt: Gitter - .. image :: https://img.shields.io/discord/327254708534116352.svg :target: https://adafru.it/discord :alt: Discord @@ -46,10 +42,50 @@ Contributions are welcome! Please read our `Code of Conduct `_ before contributing to help this project stay welcoming. -API Reference -============= +Building locally +================ + +To build this library locally you'll need to install the +`circuitpython-build-tools `_ package. + +.. code-block:: shell + + python3 -m venv .env + source .env/bin/activate + pip install circuitpython-build-tools + +Once installed, make sure you are in the virtual environment: + +.. code-block:: shell + + source .env/bin/activate + +Then run the build: + +.. code-block:: shell + + circuitpython-build-bundles --filename_prefix adafruit-circuitpython-circuitplayground --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 -.. toctree:: - :maxdepth: 2 +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_circuitplayground/index diff --git a/adafruit_circuitplayground/express.py b/adafruit_circuitplayground/express.py index 21ffe1f..827bb0e 100755 --- a/adafruit_circuitplayground/express.py +++ b/adafruit_circuitplayground/express.py @@ -131,7 +131,7 @@ def detect_taps(self): """Configure what type of tap is detected by ``cpx.tapped``. Use ``1`` for single-tap detection and ``2`` for double-tap detection. This does nothing without ``cpx.tapped``. - .. image :: /_static/accelerometer.jpg + .. image :: ../docs/_static/accelerometer.jpg :alt: Accelerometer .. code-block:: python @@ -160,7 +160,7 @@ def detect_taps(self, value): def tapped(self): """True once after a detecting a tap. Requires ``cpx.detect_taps``. - .. image :: /_static/accelerometer.jpg + .. image :: ../docs/_static/accelerometer.jpg :alt: Accelerometer Tap the CPX once for a single-tap, or quickly tap twice for a double-tap. @@ -215,7 +215,7 @@ def tapped(self): def acceleration(self): """Obtain data from the x, y and z axes. - .. image :: /_static/accelerometer.jpg + .. image :: ../docs/_static/accelerometer.jpg :alt: Accelerometer This example prints the values. Try moving the board to see how the @@ -236,7 +236,7 @@ def shake(self, shake_threshold=30): :param int shake_threshold: The threshold shake must exceed to return true (Default: 30) - .. image :: /_static/accelerometer.jpg + .. image :: ../docs/_static/accelerometer.jpg :alt: Accelerometer .. code-block:: python @@ -271,7 +271,7 @@ def shake(self, shake_threshold=30): def touch_A1(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A1. - .. image :: /_static/capacitive_touch_pad_A1.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A1.jpg :alt: Capacitive touch pad A1 .. code-block:: python @@ -291,7 +291,7 @@ def touch_A1(self): # pylint: disable=invalid-name def touch_A2(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A2. - .. image :: /_static/capacitive_touch_pad_A2.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A2.jpg :alt: Capacitive touch pad A2 .. code-block:: python @@ -311,7 +311,7 @@ def touch_A2(self): # pylint: disable=invalid-name def touch_A3(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A3. - .. image :: /_static/capacitive_touch_pad_A3.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A3.jpg :alt: Capacitive touch pad A3 .. code-block:: python @@ -331,7 +331,7 @@ def touch_A3(self): # pylint: disable=invalid-name def touch_A4(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A4. - .. image :: /_static/capacitive_touch_pad_A4.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A4.jpg :alt: Capacitive touch pad A4 .. code-block:: python @@ -351,7 +351,7 @@ def touch_A4(self): # pylint: disable=invalid-name def touch_A5(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A5. - .. image :: /_static/capacitive_touch_pad_A5.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A5.jpg :alt: Capacitive touch pad A5 .. code-block:: python @@ -371,7 +371,7 @@ def touch_A5(self): # pylint: disable=invalid-name def touch_A6(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A6. - .. image :: /_static/capacitive_touch_pad_A6.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A6.jpg :alt: Capacitive touch pad A6 .. code-block:: python @@ -391,7 +391,7 @@ def touch_A6(self): # pylint: disable=invalid-name def touch_A7(self): # pylint: disable=invalid-name """Detect touch on capacitive touch pad A7. - .. image :: /_static/capacitive_touch_pad_A7.jpg + .. image :: ../docs/_static/capacitive_touch_pad_A7.jpg :alt: Capacitive touch pad A7 .. code-block:: python @@ -413,7 +413,7 @@ def adjust_touch_threshold(self, adjustment): :param int adjustment: The desired threshold increase - .. image :: /_static/capacitive_touch_pads.jpg + .. image :: ../docs/_static/capacitive_touch_pads.jpg :alt: Capacitive touch pads .. code-block:: python @@ -443,7 +443,7 @@ def pixels(self): See `neopixel.NeoPixel` for more info. - .. image :: /_static/neopixel_numbering.jpg + .. image :: ../docs/_static/neopixel_numbering.jpg :alt: NeoPixel order diagram Here is an example that sets the first pixel green and the second red. @@ -466,7 +466,7 @@ def pixels(self): def button_a(self): """``True`` when Button A is pressed. ``False`` if not. - .. image :: /_static/button_a.jpg + .. image :: ../docs/_static/button_a.jpg :alt: Button A .. code-block:: python @@ -483,7 +483,7 @@ def button_a(self): def button_b(self): """``True`` when Button B is pressed. ``False`` if not. - .. image :: /_static/button_b.jpg + .. image :: ../docs/_static/button_b.jpg :alt: Button B .. code-block:: python @@ -502,7 +502,7 @@ def switch(self): ``True`` when the switch is to the left next to the music notes. ``False`` when it is to the right towards the ear. - .. image :: ../_static/slide_switch.jpg + .. image :: ../docs/_static/slide_switch.jpg :alt: Slide switch .. code-block:: python @@ -520,7 +520,7 @@ def switch(self): def temperature(self): """The temperature of the CircuitPlayground in Celsius. - .. image :: /_static/thermistor.jpg + .. image :: ../docs/_static/thermistor.jpg :alt: Temperature sensor Converting this to Farenheit is easy! @@ -543,7 +543,7 @@ def temperature(self): def light(self): """The brightness of the CircuitPlayground in approximate Lux. - .. image :: /_static/light_sensor.jpg + .. image :: ../docs/_static/light_sensor.jpg :alt: Light sensor Try covering the sensor next to the eye to see it change. @@ -563,7 +563,7 @@ def light(self): def red_led(self): """The red led next to the USB plug marked D13. - .. image :: /_static/red_led.jpg + .. image :: ../docs/_static/red_led.jpg :alt: D13 LED .. code-block:: python @@ -604,7 +604,7 @@ def play_tone(self, frequency, duration): :param int frequency: The frequency of the tone in Hz :param float duration: The duration of the tone in seconds - .. image :: /_static/speaker.jpg + .. image :: ../docs/_static/speaker.jpg :alt: Onboard speaker .. code-block:: python @@ -624,7 +624,7 @@ def start_tone(self, frequency): :param int frequency: The frequency of the tone in Hz - .. image :: /_static/speaker.jpg + .. image :: ../docs/_static/speaker.jpg :alt: Onboard speaker .. code-block:: python @@ -649,7 +649,7 @@ def start_tone(self, frequency): def stop_tone(self): """ Use with start_tone to stop the tone produced. - .. image :: /_static/speaker.jpg + .. image :: ../docs/_static/speaker.jpg :alt: Onboard speaker .. code-block:: python @@ -674,7 +674,7 @@ def play_file(self, file_name): :param file_name: The name of your .wav file in quotation marks including .wav - .. image :: /_static/speaker.jpg + .. image :: ../docs/_static/speaker.jpg :alt: Onboard speaker .. code-block:: python diff --git a/adafruit_circuitplayground/index.rst b/adafruit_circuitplayground/index.rst deleted file mode 100644 index 6ab6b84..0000000 --- a/adafruit_circuitplayground/index.rst +++ /dev/null @@ -1,9 +0,0 @@ - -CircuitPlayground APIs -=========================================== - -`express` - CircuitPlayground Express (CPX for short) ------------------------------------------------------ - -.. automodule:: adafruit_circuitplayground.express - :members: diff --git a/_static/accelerometer.jpg b/docs/_static/accelerometer.jpg similarity index 100% rename from _static/accelerometer.jpg rename to docs/_static/accelerometer.jpg diff --git a/_static/button_a.jpg b/docs/_static/button_a.jpg similarity index 100% rename from _static/button_a.jpg rename to docs/_static/button_a.jpg diff --git a/_static/button_b.jpg b/docs/_static/button_b.jpg similarity index 100% rename from _static/button_b.jpg rename to docs/_static/button_b.jpg diff --git a/_static/capacitive_touch_pad_A1.jpg b/docs/_static/capacitive_touch_pad_A1.jpg similarity index 100% rename from _static/capacitive_touch_pad_A1.jpg rename to docs/_static/capacitive_touch_pad_A1.jpg diff --git a/_static/capacitive_touch_pad_A2.jpg b/docs/_static/capacitive_touch_pad_A2.jpg similarity index 100% rename from _static/capacitive_touch_pad_A2.jpg rename to docs/_static/capacitive_touch_pad_A2.jpg diff --git a/_static/capacitive_touch_pad_A3.jpg b/docs/_static/capacitive_touch_pad_A3.jpg similarity index 100% rename from _static/capacitive_touch_pad_A3.jpg rename to docs/_static/capacitive_touch_pad_A3.jpg diff --git a/_static/capacitive_touch_pad_A4.jpg b/docs/_static/capacitive_touch_pad_A4.jpg similarity index 100% rename from _static/capacitive_touch_pad_A4.jpg rename to docs/_static/capacitive_touch_pad_A4.jpg diff --git a/_static/capacitive_touch_pad_A5.jpg b/docs/_static/capacitive_touch_pad_A5.jpg similarity index 100% rename from _static/capacitive_touch_pad_A5.jpg rename to docs/_static/capacitive_touch_pad_A5.jpg diff --git a/_static/capacitive_touch_pad_A6.jpg b/docs/_static/capacitive_touch_pad_A6.jpg similarity index 100% rename from _static/capacitive_touch_pad_A6.jpg rename to docs/_static/capacitive_touch_pad_A6.jpg diff --git a/_static/capacitive_touch_pad_A7.jpg b/docs/_static/capacitive_touch_pad_A7.jpg similarity index 100% rename from _static/capacitive_touch_pad_A7.jpg rename to docs/_static/capacitive_touch_pad_A7.jpg diff --git a/_static/capacitive_touch_pads.jpg b/docs/_static/capacitive_touch_pads.jpg similarity index 100% rename from _static/capacitive_touch_pads.jpg rename to docs/_static/capacitive_touch_pads.jpg diff --git a/_static/circuitplayground_express.jpg b/docs/_static/circuitplayground_express.jpg similarity index 100% rename from _static/circuitplayground_express.jpg rename to docs/_static/circuitplayground_express.jpg 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/_static/light_sensor.jpg b/docs/_static/light_sensor.jpg similarity index 100% rename from _static/light_sensor.jpg rename to docs/_static/light_sensor.jpg diff --git a/_static/neopixel_numbering.jpg b/docs/_static/neopixel_numbering.jpg similarity index 100% rename from _static/neopixel_numbering.jpg rename to docs/_static/neopixel_numbering.jpg diff --git a/_static/red_led.jpg b/docs/_static/red_led.jpg similarity index 100% rename from _static/red_led.jpg rename to docs/_static/red_led.jpg diff --git a/_static/slide_switch.jpg b/docs/_static/slide_switch.jpg similarity index 100% rename from _static/slide_switch.jpg rename to docs/_static/slide_switch.jpg diff --git a/_static/speaker.jpg b/docs/_static/speaker.jpg similarity index 100% rename from _static/speaker.jpg rename to docs/_static/speaker.jpg diff --git a/_static/thermistor.jpg b/docs/_static/thermistor.jpg similarity index 100% rename from _static/thermistor.jpg rename to docs/_static/thermistor.jpg diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..2f10513 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,5 @@ + +.. If you created a package, create one automodule per module in the package. + +.. automodule:: adafruit_circuitplayground.express + :members: diff --git a/conf.py b/docs/conf.py similarity index 91% rename from conf.py rename to docs/conf.py index 104523b..623fc90 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 CircuitPlayground 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 = 'AdafruitCircuitPlaygroundLibrarydoc' diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..bf11adc --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,32 @@ +Simple test +------------ + +Ensure your device works with this simple test. + +.. literalinclude:: ../examples/acceleration_simpletest.py + :caption: examples/acceleration_simpletest.py + :linenos: + +.. literalinclude:: ../examples/pixels_simpletest.py + :caption: examples/pixels_simpletest.py + :linenos: + +.. literalinclude:: ../examples/shake_simpletest.py + :caption: examples/shake_simpletest.py + :linenos: + +.. literalinclude:: ../examples/tapdetect_simpletest.py + :caption: examples/tapdetect_simpletest.py + :linenos: + +.. literalinclude:: ../examples/tapdetectsimple_simpletest.py + :caption: examples/tapdetectsimple_simpletest.py + :linenos: + +.. literalinclude:: ../examples/tone_simpletest.py + :caption: examples/tone_simpletest.py + :linenos: + +.. literalinclude:: ../examples/touched_simpletest.py + :caption: examples/touched_simpletest.py + :linenos: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..a66c186 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,47 @@ +.. 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 CircuitPlayground 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/acceleration.py b/examples/acceleration_simpletest.py similarity index 100% rename from examples/acceleration.py rename to examples/acceleration_simpletest.py diff --git a/examples/pixels.py b/examples/pixels_simpletest.py similarity index 100% rename from examples/pixels.py rename to examples/pixels_simpletest.py diff --git a/examples/shake.py b/examples/shake_simpletest.py similarity index 100% rename from examples/shake.py rename to examples/shake_simpletest.py diff --git a/examples/tapdetect.py b/examples/tapdetect_simpletest.py similarity index 100% rename from examples/tapdetect.py rename to examples/tapdetect_simpletest.py diff --git a/examples/tapdetectsimple.py b/examples/tapdetectsimple_simpletest.py similarity index 100% rename from examples/tapdetectsimple.py rename to examples/tapdetectsimple_simpletest.py diff --git a/examples/tone.py b/examples/tone_simpletest.py similarity index 100% rename from examples/tone.py rename to examples/tone_simpletest.py diff --git a/examples/touched.py b/examples/touched_simpletest.py similarity index 100% rename from examples/touched.py rename to examples/touched_simpletest.py