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.