Updated files to make an interesting ReadToDocs

Author: mrmcwethy

.gitignore

@@ -1,3 +1,6 @@
+__pycache__
+_build
+*.pyc
 .env
 build*
 bundles

.pylintrc

@@ -119,7 +119,8 @@ spelling-store-unknown-words=no
 [MISCELLANEOUS]
 
 # List of note tags to take in consideration, separated by a comma.
-notes=FIXME,XXX,TODO
+# notes=FIXME,XXX,TODO
+notes=FIXME,XXX
 
 
 [TYPECHECK]
@@ -300,7 +301,7 @@ function-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
 
 # Good variable names which should always be accepted, separated by a comma
 # good-names=i,j,k,ex,Run,_
-good-names=r,g,b,i,j,k,n,ex,Run,_
+good-names=r,g,b,w,i,j,k,n,x,y,z,ex,ok,Run,_
 
 # Include a hint for the correct naming format with invalid-name
 include-naming-hint=no
@@ -422,7 +423,7 @@ max-returns=6
 max-statements=50
 
 # Minimum number of public methods for a class (see R0903).
-min-public-methods=2
+min-public-methods=1
 
 
 [EXCEPTIONS]

.readthedocs.yml

@@ -0,0 +1,3 @@
+python:
+    version: 3
+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_ssd1306.py
-  - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
+  - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py)
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-ssd1306 --library_location .
+  - cd docs && sphinx-build -E -W -b html . _build/html

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 Adafruit Industries
+Copyright (c) 2016, 2017 Adafruit Industries
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -1,5 +1,124 @@
-Adafruit CircuitPython driver for SSD1306 OLED displays.
+Introduction
+============
 
-This driver is based on the SSD1306 driver in the MicroPython source but differs
-by supporting hardware I2C interfaces and Adafruit CircuitPython API.  For a
-MicroPython machine API compatible library see: https://github.com/adafruit/micropython-adafruit-ssd1306
+.. image:: https://readthedocs.org/projects/adafruit-circuitpython-ssd1306/badge/?version=latest
+    :target: https://circuitpython.readthedocs.io/projects/ssd1306/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://discord.gg/nBQh6qu
+    :alt: Discord
+
+.. image:: https://travis-ci.org/adafruit/adafruit_CircuitPython_SSD1306.svg?branch=master
+    :target: https://travis-ci.org/adafruit/adafruit_CircuitPython_SSD1306
+    :alt: Build Status
+
+    Adafruit CircuitPython driver for SSD1306 OLED displays.
+
+    This driver is based on the SSD1306 driver in the MicroPython source but differs
+    by supporting hardware I2C interfaces and Adafruit CircuitPython API.  For a
+    MicroPython machine API compatible library see: https://github.com/adafruit/micropython-adafruit-ssd1306
+
+
+Dependencies
+=============
+This driver depends on:
+
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+* `Bus Device <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice>`_
+
+Please ensure all dependencies are available on the CircuitPython filesystem.
+This is easily achieved by downloading
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
+
+Usage Example
+=============
+
+.. code-block:: python3
+
+  # Basic example of clearing and drawing pixels on a SSD1306 OLED display.
+  # This example and library is meant to work with Adafruit CircuitPython API.
+  # Author: Tony DiCola
+  # License: Public Domain
+
+  # Import all board pins.
+  from board import SCL, SDA
+  import busio
+
+  # Import the SSD1306 module.
+  import adafruit_ssd1306
+
+
+  # Create the I2C interface.
+  i2c = busio.I2C(SCL, SDA)
+
+  # Create the SSD1306 OLED class.
+  # The first two parameters are the pixel width and pixel height.  Change these
+  # to the right size for your display!
+  display = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
+  # Alternatively you can change the I2C address of the device with an addr parameter:
+  #display = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c, addr=0x31)
+
+  # Clear the display.  Always call show after changing pixels to make the display
+  # update visible!
+  display.fill(0)
+
+  display.show()
+
+
+Contributing
+============
+
+Contributions are welcome! Please read our `Code of Conduct
+<https://github.com/adafruit/adafruit_CircuitPython_SSD1306/blob/master/CODE_OF_CONDUCT.md>`_
+before contributing to help this project stay welcoming.
+
+Building locally
+================
+
+Zip release files
+-----------------
+
+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-ssd1306 --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_ssd1306.py

@@ -1,5 +1,33 @@
-"""SSD1306 OLED driver, I2C and SPI interfaces"""
-# MicroPython SSD1306 OLED driver, I2C and SPI interfaces
+# The MIT License (MIT)
+#
+# Copyright (c) 2017 Michael McWethy
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_SSD1306`
+====================================================
+
+MicroPython SSD1306 OLED driver, I2C and SPI interfaces
+
+* Author(s): Tony DiCola, Michael McWethy
+"""
+
 import time
 import framebuf