Added some more API doc content

Author: dplanella

docs/README.md

@@ -3,7 +3,7 @@
 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.
 
 ```
-├── conf.py     <- Sphinx configuration file
+├── conf.py    <- Sphinx configuration file
 ├── index.rst  <- Documentation will be generated based on this
 └── Makefile   <- Auxiliary Makefile to build documentation
 ```
@@ -54,14 +54,15 @@ For the sake of keeping things simple and with less maintenance, the approach of
 
 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.
 
-- The documentation in Python modules follows the Google readable docstring markup, which is fully supported by Sphinx.
-- The documentation in the `index.rst` file is written in [reStructuredText](http://docutils.sourceforge.net/rst.html), with Sphinx markup for defining the objects. 
+- 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 Python modules follows the Google readable docstring markup, which also builds upon reStructuredText and is fully supported by Sphinx.
 
 ## Further reference
 
 - [Google readable docstring markup](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments)
 - [Google docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
-- [More Google docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html))
+- [More Google docstring examples](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
 - [Sphinx docstring markup](http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain)
+- [reStructuredText primer](http://www.sphinx-doc.org/en/stable/rest.html#rst-primer)
 
 

docs/index.rst

@@ -3,6 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
 Adafruit Beaglebone IO Python API
 =================================
 
@@ -22,6 +26,14 @@ 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])
@@ -256,7 +268,6 @@ Example::
 
    .. method:: xfer(values[,delay=0])
 
-      xfer([values]) -> [values]
       Perform an SPI transaction of values. Slave Select (SS or CS) will be
       released and reactivated between blocks.
 
@@ -268,7 +279,6 @@ Example::
 
    .. method:: xfer2(values)
 
-      xfer2([values]) -> [values]
       Perform an SPI transaction of values. Slave Select (SS or CS) will be
       held active between blocks.
 
@@ -282,6 +292,21 @@ Example::
 
 TODO
 
+.. 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 often be using pin names for
+   better readability. 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