Improve Ref Docs

readthedocs.yml → .readthedocs.yml

@@ -1,4 +1,3 @@
 python:
     version: 3
-    pip_install: true
 requirements_file: requirements.txt

.travis.yml

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

README.rst

@@ -6,10 +6,14 @@ Adafruit CircuitPython BusDevice
     :alt: Documentation Status
 
 .. image :: https://img.shields.io/discord/327254708534116352.svg
-    :target: https://adafru.it/discord
+    :target: https://discord.gg/nBQh6qu
     :alt: Discord
 
-The `I2CDevice` and `SPIDevice` helper classes make managing transaction state
+.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_BusDevice.svg?branch=master
+    :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_BusDevice
+    :alt: Build Status
+
+The ``I2CDevice`` and ``SPIDevice`` helper classes make managing transaction state
 on a bus easy. For example, they manage locking the bus to prevent other
 concurrent access. For SPI devices, it manages the chip select and protocol
 changes such as mode. For I2C, it manages the device address.
@@ -28,9 +32,62 @@ To install:
 #. Download and unzip the `latest release zip <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/releases>`_.
 #. Copy the unzipped ``adafruit_bus_device`` to the ``lib`` directory on the ``CIRCUITPY`` drive.
 
-API
----
-.. toctree::
-    :maxdepth: 3
+Usage Example
+=============
+
+See examples/read_register_i2c.py and examples/read_register_spi.py for examples of the module's usage.
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Building locally
+================
+
+To build this library locally you'll need to install the
+`circuitpython-build-tools <https://github.com/adafruit/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-busdevice --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.
 
-    adafruit_bus_device/index

adafruit_bus_device/i2c_device.py

@@ -21,7 +21,7 @@
 # THE SOFTWARE.
 
 """
-I2C Bus Device
+`adafruit_bus_device.i2c_device` - I2C Bus Device
 ====================================================
 """
 

adafruit_bus_device/spi_device.py

@@ -22,7 +22,7 @@
 # pylint: disable=too-few-public-methods
 
 """
-SPI Bus Device
+`adafruit_bus_device.spi_device` - SPI Bus Device
 ====================================================
 """
 

docs/api.rst

@@ -0,0 +1,8 @@
+
+.. If you created a package, create one automodule per module in the package.
+
+.. automodule:: adafruit_bus_device.i2c_device
+   :members:
+
+.. automodule:: adafruit_bus_device.spi_device
+    :members:

docs/conf.py

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- General configuration ------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+]
+
+# Uncomment the below if you use native CircuitPython modules such as
+# digitalio, micropython and busio. List the modules you use. Without it, the
+# autodoc module docs will fail to generate with a warning.
+#autodoc_mock_imports = ["adafruit_bus_device", "micropython"]
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Adafruit CircuitPython Bus Device'
+copyright = u'2016-2017 Scott Shawcroft and Tony Dicola for Adafruit Industries'
+author = u'Scott Shawcroft and Tony Dicola'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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', '.env', 'CODE_OF_CONDUCT.md']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+default_role = "any"
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+add_function_parentheses = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# 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 ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
+    except:
+        html_theme = 'default'
+        html_theme_path = ['.']
+else:
+    html_theme_path = ['.']
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# 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 = 'AdafruitBusDeviceLibrarydoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'AdafruitBusDeviceLibrary.tex', u'Adafruit Bus Device Library Documentation',
+     author, 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'AdafruitBusDeviceLibrary', u'Adafruit Bus Device Library Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'AdafruitBusDeviceLibrary', u'Adafruit Bus Device Library Documentation',
+     author, 'AdafruitBusDeviceLibrary', 'One line description of project.',
+     'Miscellaneous'),
+]

docs/examples.rst

@@ -0,0 +1,12 @@
+Simple test
+------------
+
+Ensure your device works with this simple test.
+
+.. literalinclude:: ../examples/read_register_i2c.py
+    :caption: examples/read_register_i2c.py
+    :linenos:
+
+.. literalinclude:: ../examples/read_register_spi.py
+    :caption: examples/read_register_spi.py
+    :linenos:

docs/index.rst

@@ -0,0 +1,45 @@
+.. 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
+
+.. toctree::
+    :caption: Other Links
+
+    Download <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/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`