Merge pull request #5 from sommersoft/new_docs

Improve Ref Docs

Author: kattni

readthedocs.yml renamed to .readthedocs.yml

@@ -16,16 +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_featherwing/*.py
   - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/**/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-featherwing --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

.travis.yml

@@ -10,6 +10,10 @@ Introduction
     :target: https://discord.gg/nBQh6qu
     :alt: Discord
 
+.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_FeatherWing.svg?branch=master
+    :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_FeatherWing
+    :alt: Build Status
+
 This library provides FeatherWing specific classes for those that require a significant amount of
 initialization.
 
@@ -26,14 +30,6 @@ This is easily achieved by downloading
 `the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_ and highly recommended over
 installing each one.
 
-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-featherwing --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.

README.rst

@@ -47,7 +47,7 @@ def __init__(self):
     def bus_voltage(self):
         """Bus voltage returns volts.
 
-            .. image :: /_static/ina219_featherwing/ina219_featherwing.jpg
+            .. image :: ../docs/_static/ina219_featherwing/ina219_featherwing.jpg
               :alt: INA219 Featherwing
 
             This example prints the bus voltage with the appropriate units.
@@ -70,7 +70,7 @@ def bus_voltage(self):
     def shunt_voltage(self):
         """Shunt voltage returns volts.
 
-            .. image :: /_static/ina219_featherwing/ina219_featherwing.jpg
+            .. image :: ../docs/_static/ina219_featherwing/ina219_featherwing.jpg
               :alt: INA219 Featherwing
 
             This example prints the shunt voltage with the appropriate units.
@@ -93,7 +93,7 @@ def shunt_voltage(self):
     def voltage(self):
         """Voltage, known as load voltage, is bus voltage plus shunt voltage. Returns volts.
 
-            .. image :: /_static/ina219_featherwing/ina219_featherwing.jpg
+            .. image :: ../docs/_static/ina219_featherwing/ina219_featherwing.jpg
               :alt: INA219 Featherwing
 
             This example prints the voltage with the appropriate units.
@@ -117,7 +117,7 @@ def voltage(self):
     def current(self):
         """Current returns mA.
 
-            .. image :: /_static/ina219_featherwing/ina219_featherwing.jpg
+            .. image :: ../docs/_static/ina219_featherwing/ina219_featherwing.jpg
               :alt: INA219 Featherwing
 
             This example prints the current with the appropriate units.

adafruit_featherwing/ina219_featherwing.py

@@ -58,7 +58,7 @@ def __init__(self):
     def button_a(self):
         """Joy featherwing button A.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_a.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_a.jpg
               :alt: Joy FeatherWing Button A
 
             This example prints when button A is pressed.
@@ -81,7 +81,7 @@ def button_a(self):
     def button_b(self):
         """Joy featherwing button B.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_b.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_b.jpg
               :alt: Joy FeatherWing Button B
 
             This example prints when button B is pressed.
@@ -104,7 +104,7 @@ def button_b(self):
     def button_x(self):
         """Joy featherwing button X.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_x.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_x.jpg
               :alt: Joy FeatherWing Button X
 
             This example prints when button X is pressed.
@@ -127,7 +127,7 @@ def button_x(self):
     def button_y(self):
         """Joy featherwing button Y.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_y.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_y.jpg
               :alt: Joy FeatherWing Button Y
 
             This example prints when button Y is pressed.
@@ -150,7 +150,7 @@ def button_y(self):
     def button_select(self):
         """Joy featherwing button SELECT.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_select.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_select.jpg
               :alt: Joy FeatherWing Button SELECT
 
             This example prints when button SELECT is pressed.
@@ -178,7 +178,7 @@ def _check_button(self, button):
     def joystick_offset(self):
         """Offset used to correctly report (0, 0) when the joystick is centered.
 
-            .. image :: /_static/joy_featherwing/joy_featherwing_joystick.jpg
+            .. image :: ../docs/_static/joy_featherwing/joy_featherwing_joystick.jpg
               :alt: Joy FeatherWing Joystick
 
             Provide a tuple of (x, y) to set your joystick center to (0, 0).
@@ -220,7 +220,7 @@ def zero_joystick(self):
         Note: You must not be touching the joystick at the time of zeroing
         for it to be accurate.
 
-        .. image :: /_static/joy_featherwing/joy_featherwing_joystick.jpg
+        .. image :: ../docs/_static/joy_featherwing/joy_featherwing_joystick.jpg
           :alt: Joy FeatherWing Joystick
 
         This example zeros the joystick, and prints the coordinates of
@@ -252,7 +252,7 @@ def zero_joystick(self):
     def joystick(self):
         """Joy FeatherWing joystick.
 
-        .. image :: /_static/joy_featherwing/joy_featherwing_joystick.jpg
+        .. image :: ../docs/_static/joy_featherwing/joy_featherwing_joystick.jpg
           :alt: Joy FeatherWing Joystick
 
         This example zeros the joystick, and prints the coordinates of

adafruit_featherwing/joy_featherwing.py

@@ -70,7 +70,7 @@ def _motor(self, motor_name, channels, stepper_name):
     def motor1(self):
         """:py:class:`~adafruit_motor.motor.DCMotor` controls for motor 1.
 
-            .. image :: /_static/motor_featherwing/m1.jpg
+            .. image :: ../docs/_static/motor_featherwing/m1.jpg
               :alt: Motor 1 location
 
             This example moves the motor forwards for one fifth of a second at full speed.
@@ -93,7 +93,7 @@ def motor1(self):
     def motor2(self):
         """:py:class:`~adafruit_motor.motor.DCMotor` controls for motor 2.
 
-            .. image :: /_static/motor_featherwing/m2.jpg
+            .. image :: ../docs/_static/motor_featherwing/m2.jpg
               :alt: Motor 2 location
 
             This example moves the motor forwards for one fifth of a second at full speed.
@@ -116,7 +116,7 @@ def motor2(self):
     def motor3(self):
         """:py:class:`~adafruit_motor.motor.DCMotor` controls for motor 3.
 
-            .. image :: /_static/motor_featherwing/m3.jpg
+            .. image :: ../docs/_static/motor_featherwing/m3.jpg
               :alt: Motor 3 location
 
             This example moves the motor forwards for one fifth of a second at full speed.
@@ -139,7 +139,7 @@ def motor3(self):
     def motor4(self):
         """:py:class:`~adafruit_motor.motor.DCMotor` controls for motor 4.
 
-            .. image :: /_static/motor_featherwing/m4.jpg
+            .. image :: ../docs/_static/motor_featherwing/m4.jpg
               :alt: Motor 4 location
 
             This example moves the motor forwards for one fifth of a second at full speed.
@@ -163,7 +163,7 @@ def stepper1(self):
         """:py:class:`~adafruit_motor.stepper.StepperMotor` controls for one connected to stepper 1
            (also labeled motor 1 and motor 2).
 
-            .. image :: /_static/motor_featherwing/stepper1.jpg
+            .. image :: ../docs/_static/motor_featherwing/stepper1.jpg
               :alt: Stepper 1 location
 
             This example moves the stepper motor 100 steps forwards.
@@ -191,7 +191,7 @@ def stepper2(self):
         """:py:class:`~adafruit_motor.stepper.StepperMotor` controls for one connected to stepper 2
            (also labeled motor 3 and motor 4).
 
-            .. image :: /_static/motor_featherwing/stepper2.jpg
+            .. image :: ../docs/_static/motor_featherwing/stepper2.jpg
               :alt: Stepper 2 location
 
             This example moves the stepper motor 100 steps forwards.

adafruit_featherwing/motor_featherwing.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 ------------------------------------------------
 
@@ -34,7 +34,7 @@
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'README'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Adafruit featherwing Library'
@@ -60,7 +60,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.
@@ -77,6 +77,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 ----------------------------------------------
 
@@ -101,6 +104,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 = 'AdafruitFeatherwingLibrarydoc'
 

docs/_static/favicon.ico

@@ -0,0 +1,20 @@
+Simple tests
+-------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/ina219_featherwing/ina219.py
+    :caption: examples/ina219_featherwing/ina219.py
+    :linenos:
+
+.. literalinclude:: ../examples/joy_featherwing/joy.py
+    :caption: examples/joy_featherwing/joy.py
+    :linenos:
+
+.. literalinclude:: ../examples/motor_featherwing/dc_motor.py
+    :caption: examples/motor_featherwing/dc_motor.py
+    :linenos:
+
+.. literalinclude:: ../examples/motor_featherwing/stepper_motor.py
+    :caption: examples/motor_featherwing/stepper_motor.py
+    :linenos:

_static/ina219_featherwing/ina219_featherwing.jpg renamed to docs/_static/ina219_featherwing/ina219_featherwing.jpg

@@ -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 Feather Wings <https://www.adafruit.com/category/945>
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_FeatherWing/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`