From 02aa570a9bf251729298af56cfccc492a2ee2aac Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 09:15:46 -0700 Subject: [PATCH 01/10] Updated files to make an interesting ReadToDocs --- .gitignore | 3 ++ .pylintrc | 7 +-- .readthedocs.yml | 3 ++ .travis.yml | 8 +-- LICENSE | 2 +- README.rst | 127 ++++++++++++++++++++++++++++++++++++++++++-- adafruit_ssd1306.py | 32 ++++++++++- 7 files changed, 169 insertions(+), 13 deletions(-) create mode 100644 .readthedocs.yml diff --git a/.gitignore b/.gitignore index 499325a..0dd8629 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +__pycache__ +_build +*.pyc .env build* bundles diff --git a/.pylintrc b/.pylintrc index e274ba9..81d8170 100644 --- a/.pylintrc +++ b/.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] diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..f4243ad --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,3 @@ +python: + version: 3 +requirements_file: requirements.txt diff --git a/.travis.yml b/.travis.yml index 85192d6..e17230c 100644 --- a/.travis.yml +++ b/.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 diff --git a/LICENSE b/LICENSE index 19a9cd8..dc836b6 100644 --- a/LICENSE +++ b/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 diff --git a/README.rst b/README.rst index 80cb1ee..ad62b7f 100644 --- a/README.rst +++ b/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 `_ +* `Bus Device `_ + +Please ensure all dependencies are available on the CircuitPython filesystem. +This is easily achieved by downloading +`the Adafruit library and driver 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 +`_ +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 `_ 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. diff --git a/adafruit_ssd1306.py b/adafruit_ssd1306.py index 0db581e..2568508 100644 --- a/adafruit_ssd1306.py +++ b/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 From 3cdb2e7c5b902be9e5c132ddb8b832b0a93f1ef7 Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 10:52:15 -0700 Subject: [PATCH 02/10] added required new docs folder --- docs/_static/favicon.ico | Bin 0 -> 4414 bytes docs/api.rst | 8 +++ docs/conf.py | 152 +++++++++++++++++++++++++++++++++++++++ docs/examples.rst | 8 +++ docs/index.rst | 51 +++++++++++++ 5 files changed, 219 insertions(+) create mode 100644 docs/_static/favicon.ico create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/examples.rst create mode 100644 docs/index.rst diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..5aca98376a1f7e593ebd9cf41a808512c2135635 GIT binary patch literal 4414 zcmd^BX;4#F6n=SG-XmlONeGrD5E6J{RVh+e928U#MG!$jWvO+UsvWh`x&VqGNx*en zx=qox7Dqv{kPwo%fZC$dDwVpRtz{HzTkSs8QhG0)%Y=-3@Kt!4ag|JcIo?$-F|?bXVS9UDUyev>MVZQ(H8K4#;BQW-t2CPorj8^KJrMX}QK zp+e<;4ldpXz~=)2GxNy811&)gt-}Q*yVQpsxr@VMoA##{)$1~=bZ1MmjeFw?uT(`8 z^g=09<=zW%r%buwN%iHtuKSg|+r7HkT0PYN*_u9k1;^Ss-Z!RBfJ?Un4w(awqp2b3 z%+myoFis_lTlCrGx2z$0BQdh+7?!JK#9K9@Z!VrG zNj6gK5r(b4?YDOLw|DPRoN7bdP{(>GEG41YcN~4r_SUHU2hgVtUwZG@s%edC;k7Sn zC)RvEnlq~raE2mY2ko64^m1KQL}3riixh?#J{o)IT+K-RdHae2eRX91-+g!y`8^># z-zI0ir>P%Xon)!@xp-BK2bDYUB9k613NRrY6%lVjbFcQc*pRqiK~8xtkNPLxt}e?&QsTB}^!39t_%Qb)~Ukn0O%iC;zt z<&A-y;3h++)>c1br`5VFM~5(83!HKx$L+my8sW_c#@x*|*vB1yU)_dt3vH;2hqPWx zAl^6@?ipx&U7pf`a*>Yq6C85nb+B=Fnn+(id$W#WB^uHAcZVG`qg;rWB}ubvi(Y>D z$ei>REw$#xp0SHAd^|1hq&9HJ=jKK8^zTH~nk)G?yUcmTh9vUM6Y0LMw4(gYVY$D$ zGl&WY&H<)BbJ&3sYbKjx1j^=3-0Q#f^}(aP1?8^`&FUWMp|rmtpK)bLQ1Zo?^s4jqK=Lfg*9&geMGVQ z#^-*!V`fG@;H&{M9S8%+;|h&Qrxym0Ar>WT4BCVLR8cGXF=JmEYN(sNT(9vl+S|%g z8r7nXQ(95i^`=+XHo|){$vf2$?=`F$^&wFlYXyXg$B{a>$-Fp+V}+D;9k=~Xl~?C4 zAB-;RKXdUzBJE{V&d&%R>aEfFe;vxqI$0@hwVM}gFeQR@j}a>DDxR+n+-*6|_)k%% z*mSpDV|=5I9!&VC&9tD%fcVygWZV!iIo2qFtm#!*(s|@ZT33*Ad;+<|3^+yrp*;oH zBSYLV(H1zTU?2WjrCQoQW)Z>J2a=dTriuvezBmu16`tM2fm7Q@d4^iqII-xFpwHGI zn9CL}QE*1vdj2PX{PIuqOe5dracsciH6OlAZATvE8rj6ykqdIjal2 z0S0S~PwHb-5?OQ-tU-^KTG@XNrEVSvo|HIP?H;7ZhYeZkhSqh-{reE!5di;1zk$#Y zCe7rOnlzFYJ6Z#Hm$GoidKB=2HBCwm`BbZVeZY4ukmG%1uz7p2URs6c9j-Gjj^oQV zsdDb3@k2e`C$1I5ML5U0Qs0C1GAp^?!*`=|Nm(vWz3j*j*8ucum2;r0^-6Aca=Gv) zc%}&;!+_*S2tlnnJnz0EKeRmw-Y!@9ob!XQBwiv}^u9MkaXHvM=!<3YX;+2#5Cj5pp?FEK750S3BgeSDtaE^ zXUM@xoV6yBFKfzvY20V&Lr0yC + CircuitPython Reference Documentation + CircuitPython Support Forum + Discord Chat + Adafruit Learning System + Adafruit Blog + Adafruit Store + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` From 26cb9bfbb11127c0f51721b8250cd4be869924d5 Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 11:14:35 -0700 Subject: [PATCH 03/10] added missing comma --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 0eb04c0..4e49344 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', - 'sphinx.ext.napoleon' + 'sphinx.ext.napoleon', 'sphinx.ext.todo', ] From 2a557cb08de43f53eee6e656175c547b6d6bf832 Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 11:21:23 -0700 Subject: [PATCH 04/10] added these files as well --- CODE_OF_CONDUCT.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 1 + 2 files changed, 75 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 requirements.txt diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1617586 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at support@adafruit.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..c47d35a --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +adafruit-circuitpython-bus-device From 3fafe54d0d77c549582750ff0c1bef1ab42e8933 Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 11:37:28 -0700 Subject: [PATCH 05/10] updated the autodoc_mock keyword --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 4e49344..4c91afa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ # 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 = ["digitalio", "busio"] +autodoc_mock_imports = [ "framebuf", "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)} From 432fa6e05e5c42ad987ce02ac8c7ebd097ac4b1d Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 11:41:35 -0700 Subject: [PATCH 06/10] updated the examples.rst to get the right filename --- docs/examples.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/examples.rst b/docs/examples.rst index e3e2780..1af3138 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -3,6 +3,6 @@ Simple test Ensure your device works with this simple test. -.. literalinclude:: ../examples/ssd1306_simpletest.py - :caption: examples/ssd1306_simpletest.py +.. literalinclude:: ../examples/simpletest.py + :caption: examples/simpletest.py :linenos: From 86fc1626657f75314254551f82cda3e7af7a23cf Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 12:36:47 -0700 Subject: [PATCH 07/10] fix a web address --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index ad62b7f..6a7c52a 100644 --- a/README.rst +++ b/README.rst @@ -9,8 +9,8 @@ Introduction :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 +.. 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. From 615458ceb5357cc39071e68cfae1d8a63951af1f Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 12:45:39 -0700 Subject: [PATCH 08/10] outdented from description text --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 6a7c52a..3e71492 100644 --- a/README.rst +++ b/README.rst @@ -13,11 +13,11 @@ Introduction :target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_SSD1306 :alt: Build Status - Adafruit CircuitPython driver for SSD1306 OLED displays. +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 +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 From 2c9a90eaf38cd3430a20faf777f62790ecf1449b Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 12:56:36 -0700 Subject: [PATCH 09/10] removed todo's from README.rst --- docs/index.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index cf7f886..10c809d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,14 +23,12 @@ Table of Contents .. toctree:: :caption: Tutorials -.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave - the toctree above for use later. + CircuitPython Hardware: SSD1306 OLED Display .. toctree:: :caption: Related Products -.. todo:: Add any product links here. If there are none, then simply delete this todo and leave - the toctree above for use later. + Several SSD1306-based products .. toctree:: :caption: Other Links From c4f321ebd17deed9a7c83b70d5e593df8e7dc83b Mon Sep 17 00:00:00 2001 From: mrmcwethy Date: Mon, 19 Feb 2018 13:02:17 -0700 Subject: [PATCH 10/10] case changed on module name --- adafruit_ssd1306.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adafruit_ssd1306.py b/adafruit_ssd1306.py index 2568508..4abe3eb 100644 --- a/adafruit_ssd1306.py +++ b/adafruit_ssd1306.py @@ -20,7 +20,7 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN # THE SOFTWARE. """ -`adafruit_SSD1306` +`adafruit_ssd1306` ==================================================== MicroPython SSD1306 OLED driver, I2C and SPI interfaces