Merge pull request #221 from dplanella/readthedocs

Separate API docs into modules

Author: pdp7

docs/ADC.rst

@@ -0,0 +1,45 @@
+:mod:`ADC` --- A/D Converter input interface
+--------------------------------------------
+
+This module enables reading analog input values from the analog to digital
+converter (ADC) on the Beaglebone processor.
+
+Example::
+
+    import Adafruit_BBIO.ADC as ADC
+
+    ADC.setup()
+
+    # The read method returns normalized values from 0 to 1.0
+    value = ADC.read("P9_40")
+
+    # The read_raw returns non-normalized values from 0 to 4095
+    value = ADC.read_raw("P9_40")
+
+.. module:: Adafruit_BBIO.ADC
+
+.. function:: setup_adc()
+
+   Setup and start the ADC hardware.
+
+.. function:: setup_read(channel)
+
+   Read the normalized analog value for the channel.
+
+   :param str channel: GPIO channel to read the value from (e.g. "P8_16").
+   :returns: normalized value reading from 0.0 to 1.0
+   :rtype: float
+
+
+.. function:: setup_read_raw(channel)
+
+   Read the raw analog value for the channel.
+   
+   :note: Kernels older than 4.1.x returned a raw value range based on
+       the reference voltage of 1.8 V–– from 0 to 1800.
+
+   :param str channel: GPIO channel to read the value from (e.g. "P8_16").
+   :returns: raw value reading from 0 to 4095 (12 bits).
+   :rtype: float
+
+

docs/Encoder.rst

@@ -0,0 +1,5 @@
+:mod:`Encoder` --- Quadrature Encoder interface
+-----------------------------------------------
+
+.. automodule:: Adafruit_BBIO.Encoder
+   :members:

docs/GPIO.rst

@@ -0,0 +1,194 @@
+:mod:`GPIO` --- General Purpose I/O interface
+---------------------------------------------
+
+This module provides access and control of pins set up as General Purpose
+I/O (GPIO).
+
+.. note::
+
+   You need to be part of the ``gpio`` group of the OS running on the
+   Beaglebone to be able to run GPIO code as a non-root user. The default
+   user created upon the Debian image installation should already be
+   part of the group. Otherwise, you can use
+   ``sudo usermod -a -G gpio userName`` to add ``userName`` to the group.
+
+.. note::
+
+   When coding with this module, you will be using pin names for
+   better readability. As such, you can specify them in the header 8 or 9
+   form (e.g. "P8_16") or in pin name form (e.g. "GPIO1_14").
+   For easy reference, you can use the
+   `Beaglebone pin names table <https://github.com/adafruit/adafruit-beaglebone-io-python/blob/master/source/common.c#L73>`_
+
+
+Example::
+
+    # Use the config-pin command line tool to set a pin's function to GPIO
+    # Then you can control it with the GPIO module from Python
+    config-pin P9_14 gpio
+
+    import Adafruit_BBIO.GPIO as GPIO
+
+    # Set up pins as inputs or outputs
+    GPIO.setup("P8_13", GPIO.IN)
+    GPIO.setup("P8_14", GPIO.OUT)
+    GPIO.setup("GPIO0_26", GPIO.OUT)  # Alternative: use actual pin names
+
+    # Write a logic high or logic low
+    GPIO.output("P8_14", GPIO.HIGH)  # You can also write '1' instead
+    GPIO.output("P8_14", GPIO.LOW)   # You can also write '0' instead
+
+.. module:: Adafruit_BBIO.GPIO
+
+.. function:: setup(channel, direction[, pull_up_down=PUD_OFF, initial=None, delay=0])
+
+   Set up the given GPIO channel, its direction and (optional) pull/up down control
+
+   :param str channel: GPIO channel to set up (e.g. "P8_16").
+   :param int direction: GPIO channel direction (:data:`IN` or :data:`OUT`).
+   :param int pull_up_down: pull-up/pull-down resistor configuration
+       (:data:`PUD_OFF`, :data:`PUD_UP` or :data:`PUD_DOWN`).
+   :param int initial: initial value for an output channel (:data:`LOW`/:data:`HIGH`).
+   :param int delay: time in milliseconds to wait after exporting the GPIO pin.
+
+.. function:: cleanup()
+
+   Clean up by resetting all GPIO channels that have been used by
+   the application to :data:`IN` with no pullup/pulldown and no event
+   detection.
+
+   :note: It's recommended that you call this function upon exiting your
+       application.
+
+.. function:: output(channel, value)
+
+   Set the given output channel to the given digital value.
+
+   :param str channel: GPIO channel to output the value to (e.g. "P8_16").
+   :param value: value to set the output to-- 0/1 or False/True
+       or :data:`LOW`/:data:`HIGH`.
+   :type value: int or bool
+
+.. function:: input(channel)
+
+   Get the given input channel's digital value.
+
+   :param str channel: GPIO channel to read the value from (e.g. "P8_16").
+   :returns: Channel value–– 0 or 1.
+   :rtype: int
+
+.. function:: add_event_detect(channel, edge[, callback=None, bouncetime=0])
+
+   Enable edge detection events for the given GPIO channel.
+
+   :param str channel: GPIO channel to detect events from (e.g. "P8_16").
+   :param int edge: edge to detect–– :data:`RISING`, :data:`FALLING`
+       or :data:`BOTH`
+   :param func callback: a function to call once the event has been detected.
+   :param int bouncetime: switch bounce timeout in ms for the callback.
+
+.. function:: remove_event_detect(channel)
+
+   Remove edge detection for the given GPIO channel.
+
+   :param str channel: GPIO channel to remove event detection
+       from (e.g. "P8_16").
+
+.. function:: event_detected(channel)
+
+   Checks if an edge event has occured on a given GPIO.
+
+   :note: You need to enable edge detection using :func:`add_event_detect()` first.
+
+   :param str channel: GPIO channel to check for event detection
+       for (e.g. "P8_16").
+   :returns: True if an edge has occured on a given GPIO, False otherwise
+   :rtype: bool
+
+.. function:: add_event_callback(channel, callback[, bouncetime=0])
+
+   Add a callback for an event already defined using :func:`add_event_detect()`
+
+   :param str channel: GPIO channel to add a callback to (e.g. "P8_16").
+   :param func callback: a function to call once the event has been detected.
+   :param int bouncetime: switch bounce timeout in ms for the callback.
+
+.. function:: wait_for_edge(channel, edge[, timeout=-1])
+
+   Wait for an edge on the given channel.
+
+   :param str channel: GPIO channel to wait on (e.g. "P8_16").
+   :param int edge: edge to detect–– :data:`RISING`, :data:`FALLING`
+       or :data:`BOTH`
+   :param int timeout: time to wait for an edge, in milliseconds.
+       -1 will wait forever.
+
+.. function:: gpio_function(channel)
+
+   Return the current GPIO function
+   (:data:`IN`, :data:`IN`, :data:`ALT0`) of the given pin.
+
+   :warning: Currently only returning the direction of the
+       pin (input or output) is supported.
+
+   :param str channel: GPIO pin to query the status of.
+   :returns: 0 if :data:`IN`, 1 if :data:`OUT`
+   :rtype: int
+
+.. function:: setwarnings(gpio_warnings)
+
+   Enable or disable GPIO warning messages.
+
+   :warning: Currently enabling or disabling warnings
+       has no effect.
+
+   :param int gpio_warnings: 0–– disable warnings; 1–– enable warnings
+
+.. attribute:: ALT0
+
+   Pin mode-- alternate function 0.
+
+.. attribute:: BOTH
+
+   Edge detection-- detect both edges.
+
+.. attribute:: FALLING
+
+   Edge detection-- detect falling edge.
+
+.. attribute:: HIGH
+
+   Pin status-- logic low.
+
+.. attribute:: IN
+
+   Pin mode-- input.
+
+.. attribute:: LOW
+
+   Pin status-- logic low.
+
+.. attribute:: OUT
+
+   Pin mode-- output.
+
+.. attribute:: PUD_OFF
+
+   Pull-up/pull-down resistor type-- no pull-up/pull-down.
+
+.. attribute:: PUD_DOWN
+
+   Pull-up/pull-down resistor type-- pull-down.
+
+.. attribute:: PUD_UP
+
+   Pull-up/pull-down resistor type-- pull-up.
+
+.. attribute:: RISING
+
+   Edge detection-- detect rising edge.
+
+.. attribute:: VERSION
+
+   GPIO module version. Currently unused.
+

docs/PWM.rst

@@ -0,0 +1,62 @@
+:mod:`PWM` --- Pulse Width Modulation interface
+-----------------------------------------------
+
+Enables access to the Pulse Width Modulation (PWM) module, to easily and
+accurately generate a PWM output signal of a given duty cycle and
+frequency.
+
+.. note::
+
+   You need to be part of the ``pwm`` group of the OS running on the
+   Beaglebone to be able to run PWM code as a non-root user. The default
+   user created upon the Debian image installation should already be
+   part of the group. Otherwise, you can use
+   ``sudo usermod -a -G pwm userName`` to add ``userName`` to the group.
+
+.. module:: Adafruit_BBIO.PWM
+
+.. function:: start(channel, duty_cycle[, frequency=2000, polarity=0])
+
+   Set up and start the given PWM channel.
+
+   :param str channel: PWM channel. It can be specified in the form
+       of of 'P8_10', or 'EHRPWM2A'.
+   :param int duty_cycle: PWM duty cycle. It must have a value from 0 to 100.
+   :param int frequency: PWM frequency, in Hz. It must be greater than 0.
+   :param int polarity: defines whether the value for ``duty_cycle`` affects the
+       rising edge or the falling edge of the waveform. Allowed values -- 0
+       (rising edge, default) or 1 (falling edge).
+
+.. function:: stop(channel)
+
+   Stop the given PWM channel.
+
+   :param str channel: PWM channel. It can be specified in the form
+       of of 'P8_10', or 'EHRPWM2A'.
+
+.. function:: set_duty_cycle(channel, duty_cycle)
+
+   Change the duty cycle of the given PWM channel.
+
+   :note: You must have started the PWM channel with :func:`start()`
+       once, before changing the duty cycle.
+
+   :param str channel: PWM channel. It can be specified in the form
+       of of 'P8_10', or 'EHRPWM2A'.
+   :param int duty_cycle: PWM duty cycle. It must have a value from 0 to 100.
+
+.. function:: set_frequency(channel, frequency)
+
+   Change the frequency of the given PWM channel.
+
+   :note: You must have started the PWM channel with :func:`start()`
+       once, before changing the frequency.
+
+   :param str channel: PWM channel. It can be specified in the form
+       of of 'P8_10', or 'EHRPWM2A'.
+   :param int frequency: PWM frequency. It must be greater than 0.
+
+.. function:: cleanup()
+
+   Clean up by resetting all GPIO channels that have been used by this
+   program to INPUT, with no pullup/pulldown and no event detection.

docs/README.md

@@ -1,14 +1,14 @@
 # Generating API documentation 
 
-This folder contains the required files to automatically generate the Adafruit Beaglebone I/O Python API documentation, partly from the code docstrings and partly from a reStructuredText-formatted `index.rst` file.
+This folder contains the required files to automatically generate the Adafruit Beaglebone I/O Python API documentation, partly from the code docstrings and partly from files in reStructuredText format.
 
 ```
 ├── conf.py    <- Sphinx configuration file
-├── index.rst  <- Documentation will be generated based on this
+├── index.rst  <- Documentation will be generated based on the master index
 └── Makefile   <- Auxiliary Makefile to build documentation
 ```
 
-The tools used are [Sphinx](http://www.sphinx-doc.org) to extract the documentation and publish it in HTML format for online viewing, in combination with [Readthedocs](http://readthedocs.io), which automatically executes Sphinx via webhooks triggered by Github commits, and publishes the resulting docs for all tracked branches. Generally Readthedocs will be set up to track stable release branches and master.
+The tools used are [Sphinx](http://www.sphinx-doc.org) to extract the documentation and publish it in HTML format for online viewing, in combination with [Readthedocs](http://readthedocs.io). Readthedocs automatically executes Sphinx via webhooks triggered by Github commits, and publishes the resulting docs for all tracked branches or tags. Generally Readthedocs will be set up to track stable release tags and the master branch.
 
 ## Building the documentation
 
@@ -36,7 +36,7 @@ Notes:
 
 ## Readthedocs maintenance
 
-At every release that includes documenation (most probably 1.0.10 will be the first one), the release's branch needs to be selected in the web UI and marked as active.
+At every release that includes documenation (most probably 1.0.10 will be the first one), the release's branch or tag needs to be selected in the web UI and marked as active.
 
 After this, documentation will automatically be generated and published for that release. It will be available at the same URL as the main documentation, and a link with the version number will be shown, where it can be accessed from.
 
@@ -50,11 +50,11 @@ Ideally, all API documentation would be written in the source files as Python do
 
 However, most of the code is written as C extensions. While they do provide docstrings once they are built, Sphinx does not natively support extracting them. There is [a workaround](https://stackoverflow.com/a/30110104/9022675) to do this, but it involves first building the extensions, installing them and hardcoding a path. While it might work for locally-built documentation, it's unlikely that readthedocs support this option.
 
-For the sake of keeping things simple and with less maintenance, the approach of documenting the C-generated API in the `index.rst` file has been taken.
+For the sake of keeping things simple and with less maintenance, the approach of documenting the C-generated API in separate `.rst` files (one for each Python module) has been taken.
 
-This has the advantage of having a definition of the API in one place, but it also poses the disadvantage of some duplication, as the C modules do define some docstrings for their objects. Then again, the API itself has hardly changed in the last few years, and the Beaglebone is a mature platform, so it's unlikely that this will pose a significant maintenance overhead.
+This has the advantage of having a definition of the API in one place, but it also poses the disadvantage of some duplication, as the C modules do define some docstrings for their objects. Then again, the API itself has hardly changed in the last few years, and the Beaglebone is a mature platform, so it's unlikely that this will add a significant maintenance overhead.
 
-- The documentation in the `index.rst` file is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), extended with Sphinx markup for defining the objects.
+- The documentation in the `.rst` files is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), extended with Sphinx markup for defining the objects.
 - The documentation in Python modules follows the Google readable docstring markup, which also builds upon reStructuredText and is fully supported by Sphinx.
 
 ## Further reference