diff --git a/readthedocs.yml b/.readthedocs.yml similarity index 100% rename from readthedocs.yml rename to .readthedocs.yml diff --git a/.travis.yml b/.travis.yml index a18f1d6..d0c4a0b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,15 +16,16 @@ deploy: provider: releases api_key: $GITHUB_TOKEN file_glob: true - file: bundles/* + file: $TRAVIS_BUILD_DIR/bundles/* skip_cleanup: true on: tags: true install: - - pip install pylint circuitpython-build-tools + - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme script: - pylint adafruit_character_lcd/*.py - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py) - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-charlcd --library_location . + - cd docs && sphinx-build -E -W -b html . _build/html diff --git a/README.md b/README.rst similarity index 50% rename from README.md rename to README.rst index 795ce11..cbc7ce3 100644 --- a/README.md +++ b/README.rst @@ -2,10 +2,18 @@ Introduction ============ +.. image:: https://readthedocs.org/projects/adafruit-circuitpython-charlcd/badge/?version=latest + :target: https://circuitpython.readthedocs.io/projects/charlcd/en/latest/ + :alt: Documentation Status + +.. image :: https://img.shields.io/discord/327254708534116352.svg + :target: https://discord.gg/nBQh6qu + :alt: Discord + This library is compatible with standard Character LCDs such as: -* [Adafruit Standard LCD 16x2](https://www.adafruit.com/product/181) -* [Adafruit RGB backlight negative LCD 16x2](https://www.adafruit.com/product/399) -* [Adafruit RGB backlight negative LCD 20x4](https://www.adafruit.com/product/498) +* `Adafruit Standard LCD 16x2 `_ +* `Adafruit RGB backlight negative LCD 16x2 `_ +* `Adafruit RGB backlight negative LCD 20x4 `_ Compatible with CircuitPython Versions: 2.x @@ -13,23 +21,30 @@ Dependencies ============= This driver depends on: -* [Adafruit CircuitPython](https://github.com/adafruit/circuitpython "CircuitPython") +* `Adafruit CircuitPython `_ + +I2C & SPI displays also depend on: +* `Bus Device `_ 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) +`the Adafruit library and driver bundle `_. Usage Example ============= The ``Character_LCD`` class interfaces a predefined Character LCD display with CircuitPython. +.. code-block:: python + import adafruit_character_lcd You must define the data pins (``RS``, ``EN``, ``D4``, ``D5``, ``D6``, ``D7``) in your code before using the ``Character_LCD`` class. If you want to have on/off ``backlight`` functionality, you can also define your backlight as ``lcd_backlight``. Otherwise, the backlight will always remain on. An example of this is below +.. code-block:: python + lcd_rs = digitalio.DigitalInOut(D7) lcd_en = digitalio.DigitalInOut(D8) lcd_d7 = digitalio.DigitalInOut(D12) @@ -40,16 +55,22 @@ If you want to have on/off ``backlight`` functionality, you can also define your You must also define the size of the CharLCD by specifying its ``lcd_columns`` and ``lcd_rows``: +.. code-block:: python + lcd_columns = 16 lcd_rows = 2 After you have set up your LCD, we can make the device by calling it +.. code-block:: python + lcd = adafruit_character_lcd.Character_LCD(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows, lcd_backlight) To verify that your pins are correct, print a hello message to the CharLCD: +.. code-block:: python + lcd.message('hello\ncircuitpython') @@ -73,9 +94,49 @@ To install: #. Download and unzip the `latest release zip `_. #. Copy the unzipped ``adafruit_character_lcd`` to the ``lib`` directory on the ``CIRCUITPY`` or ``MICROPYTHON`` drive. -API -=== -.. toctree:: - :maxdepth: 3 +Building locally +================ + +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-charlcd --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 - api +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. \ No newline at end of file diff --git a/adafruit_character_lcd/character_lcd.py b/adafruit_character_lcd/character_lcd.py index b516c49..4b5abd9 100644 --- a/adafruit_character_lcd/character_lcd.py +++ b/adafruit_character_lcd/character_lcd.py @@ -1,4 +1,3 @@ -"""Character_LCD - module for interfacing with character lcds # The MIT License (MIT) # # Copyright (c) 2017 Brent Rubell for Adafruit Industries @@ -20,16 +19,30 @@ # 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_CircuitPython_CharLCD` +""" +`adafruit_character_lcd.character_lcd` ==================================================== -* Author(s): --Brent Rubell --Asher Lieber --Tony DiCola for the original python charLCD library -:mod:`adafruit_character_lcd` -================================================= -module for interfacing with character lcds""" +Module for interfacing with monochromatic character LCDs + +* Author(s): Brent Rubell, Asher Lieber, Tony DiCola (original python charLCD library) + +Implementation Notes +-------------------- + +**Hardware:** + +* Adafruit `Character LCDs + `_ + +**Software and Dependencies:** + +* Adafruit CircuitPython firmware (2.2.0+) for the ESP8622 and M0-based boards: + https://github.com/adafruit/circuitpython/releases +* Adafruit's Bus Device library (when using I2C/SPI): + https://github.com/adafruit/Adafruit_CircuitPython_BusDevice + +""" import time import digitalio @@ -113,17 +126,19 @@ def _set_bit(byte_value, position, val): #pylint: disable-msg=too-many-instance-attributes class Character_LCD(object): - """ Interfaces with a character LCD - :param ~digitalio.DigitalInOut rs: The reset data line - :param ~digitalio.DigitalInOut en: The enable data line - :param ~digitalio.DigitalInOut d4: The data line 4 - :param ~digitalio.DigitalInOut d5: The data line 5 - :param ~digitalio.DigitalInOut d6: The data line 6 - :param ~digitalio.DigitalInOut d7: The data line 7 - :param cols: The columns on the charLCD - :param lines: The lines on the charLCD - :param ~digitalio.DigitalInOut backlight: The backlight pin, usually - the last pin. Check with your datasheet + """ + Interfaces with a character LCD + :param ~digitalio.DigitalInOut rs: The reset data line + :param ~digitalio.DigitalInOut en: The enable data line + :param ~digitalio.DigitalInOut d4: The data line 4 + :param ~digitalio.DigitalInOut d5: The data line 5 + :param ~digitalio.DigitalInOut d6: The data line 6 + :param ~digitalio.DigitalInOut d7: The data line 7 + :param cols: The columns on the charLCD + :param lines: The lines on the charLCD + :param ~digitalio.DigitalInOut backlight: The backlight pin, usually + the last pin. Check with your datasheet + """ #pylint: disable-msg=too-many-arguments def __init__(self, rs, en, d4, d5, d6, d7, cols, lines, @@ -180,8 +195,11 @@ def clear(self): time.sleep(0.003) def show_cursor(self, show): - """Show or hide the cursor - :param show: True to show cursor, False to hide + """ + Show or hide the cursor + + :param show: True to show cursor, False to hide + """ if show: self.displaycontrol |= LCD_CURSORON @@ -190,9 +208,12 @@ def show_cursor(self, show): self._write8(LCD_DISPLAYCONTROL | self.displaycontrol) def set_cursor(self, col, row): - """Sets the cursor to ``row`` and ``col`` - :param col: column location - :param row: row location + """ + Sets the cursor to ``row`` and ``col`` + + :param col: column location + :param row: row location + """ # Clamp row to the last row of the display if row > self.lines: @@ -201,8 +222,11 @@ def set_cursor(self, col, row): self._write8(LCD_SETDDRAMADDR | (col + LCD_ROW_OFFSETS[row])) def blink(self, blink): - """Blinks the cursor if blink = true. - :param blink: True to blink, False no blink + """ + Blinks the cursor if blink = true. + + :param blink: True to blink, False no blink + """ if blink is True: self.displaycontrol |= LCD_BLINKON @@ -229,8 +253,11 @@ def set_right_to_left(self): self._write8(LCD_ENTRYMODESET | self.displaymode) def enable_display(self, enable): - """Enable or disable the display. - :param enable: True to enable display, False to disable + """ + Enable or disable the display. + + :param enable: True to enable display, False to disable + """ if enable: self.displaycontrol |= LCD_DISPLAYON @@ -272,8 +299,11 @@ def _pulse_enable(self): time.sleep(0.0000001) def set_backlight(self, lighton): - """ Set lighton to turn the charLCD backlight on. - :param lighton: True to turn backlight on, False to turn off + """ + Set lighton to turn the charLCD backlight on. + + :param lighton: True to turn backlight on, False to turn off + """ if lighton: self.backlight.value = 0 @@ -282,8 +312,10 @@ def set_backlight(self, lighton): def message(self, text): - """Write text to display, can include \n for newline - :param text: string to display + """ + Write text to display. Can include ``\\n`` for newline. + + :param text: text string to display """ line = 0 # iterate thru each char @@ -299,13 +331,15 @@ def message(self, text): self._write8(ord(char), True) def create_char(self, location, pattern): - """Fill one of the first 8 CGRAM locations with custom characters. + """ + Fill one of the first 8 CGRAM locations with custom characters. The location parameter should be between 0 and 7 and pattern should provide an array of 8 bytes containing the pattern. E.g. you can easyly design your custom character at http://www.quinapalus.com/hd44780udg.html To show your custom character use eg. lcd.message('\x01') - :param location: integer in range(8) to store the created character - :param ~bytes pattern: len(8) describes created character + + :param location: integer in range(8) to store the created character + :param ~bytes pattern: len(8) describes created character """ # only position 0..7 are allowed diff --git a/adafruit_character_lcd/character_lcd_rgb.py b/adafruit_character_lcd/character_lcd_rgb.py index 3469cee..25421f6 100755 --- a/adafruit_character_lcd/character_lcd_rgb.py +++ b/adafruit_character_lcd/character_lcd_rgb.py @@ -1,4 +1,3 @@ -"""Character_LCD_RGB - module for interfacing with character lcds # The MIT License (MIT) # # Copyright (c) 2017 Brent Rubell for Adafruit Industries @@ -20,20 +19,32 @@ # 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_CircuitPython_CharLCD` +""" +`adafruit_character_lcd.character_lcd_rgb` ==================================================== +Character_LCD - module for interfacing with RGB character LCDs * Author(s): --Brent Rubell --Asher Lieber --Tony DiCola for the original python charLCD library + -Brent Rubell + -Asher Lieber + -Tony DiCola for the original python charLCD library + +Implementation Notes +-------------------- + +**Hardware:** + +* Adafruit `Character LCDs + `_ + +**Software and Dependencies:** +* Adafruit CircuitPython firmware (2.2.0+) for the ESP8622 and M0-based boards: + https://github.com/adafruit/circuitpython/releases +* Adafruit's Bus Device library (when using I2C/SPI): + https://github.com/adafruit/Adafruit_CircuitPython_BusDevice -:mod:`adafruit_character_lcd_RGB` -================================================= -module for interfacing with RGB character lcds """ import time import digitalio diff --git a/adafruit_character_lcd/mcp23008.py b/adafruit_character_lcd/mcp23008.py index 37ee763..e777121 100644 --- a/adafruit_character_lcd/mcp23008.py +++ b/adafruit_character_lcd/mcp23008.py @@ -1,10 +1,17 @@ -"""MCP23008 I2C GPIO Extender Driver +""" +`adafruit_character_lcd.mcp23008` +========================================= + +MCP23008 I2C GPIO Extender Driver Bare-bones driver for the MCP23008 driver, as used by the character LCD backpack. This exposes the MCP2308 and its pins as standard CircuitPython digitalio pins. Currently this is integrated in the character LCD class for simplicity and reduction in dependent imports, but it could be broken out -into a standalone library later.""" -# Author: Tony DiCola +into a standalone library later. + +* Author: Tony DiCola + +""" import digitalio import adafruit_bus_device.i2c_device as i2c_device diff --git a/adafruit_character_lcd/shift_reg_74hc595.py b/adafruit_character_lcd/shift_reg_74hc595.py index 87e847d..bc52de5 100644 --- a/adafruit_character_lcd/shift_reg_74hc595.py +++ b/adafruit_character_lcd/shift_reg_74hc595.py @@ -1,11 +1,16 @@ -"""74HC595 Serial to Paralllel Shift Register Driver +""" +`adafruit_character_led.shift_reg_74hc595` +=============================================== + +74HC595 Serial to Paralllel Shift Register Driver Bare-bones driver for the 74HC595, as used by the character LCD backpack. This exposes the 74HC595 and its pins as standard CircuitPython digitalio pins. Currently this is integrated in the character LCD class for simplicity and reduction in dependent imports, but it could be broken out into a standalone library later. + +* Author: Tony DiCola """ -# Author: Tony DiCola import digitalio import adafruit_bus_device.spi_device as spi_device diff --git a/api.rst b/api.rst deleted file mode 100644 index 96b1a0d..0000000 --- a/api.rst +++ /dev/null @@ -1,12 +0,0 @@ - -`Character_LCD` - for interfacing with character lcds -+++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. automodule:: adafruit_character_lcd.character_lcd - :members: - -`Character_LCD_RGB` - for interfacing with RGB character lcds -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. automodule:: adafruit_character_lcd.character_lcd_RGB - :members: diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000..5aca983 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..fdb9d6c --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,5 @@ + +.. If you created a package, create one automodule per module in the package. + +.. automodule:: adafruit_character_lcd.character_lcd + :members: \ No newline at end of file diff --git a/conf.py b/docs/conf.py similarity index 85% rename from conf.py rename to docs/conf.py index b16c5c2..63a367a 100644 --- a/conf.py +++ b/docs/conf.py @@ -2,7 +2,7 @@ import os import sys -sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('..')) # -- General configuration ------------------------------------------------ @@ -15,8 +15,10 @@ 'sphinx.ext.viewcode', ] -autodoc_mock_imports = ["digitalio", "micropython"] - +# 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 = ["micropython", "digitalio", "addfruit_bus_device"] intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)} @@ -26,7 +28,7 @@ source_suffix = '.rst' # The master toctree document. -master_doc = 'README' +master_doc = 'index' # General information about the project. project = u'Adafruit CIRCUITPYTHON_CHARLCD Library' @@ -52,7 +54,7 @@ # 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'] +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. @@ -69,6 +71,9 @@ # 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 ---------------------------------------------- @@ -93,6 +98,12 @@ # 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 = 'AdafruitCIRCUITPYTHON_CHARLCDLibrarydoc' diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..9237e45 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,20 @@ +Simple test +------------ + +Ensure your device works with this simple test. + +.. literalinclude:: ../examples/charlcd_mono_simpletest.py + :caption: examples/charlcd_mono_simpletest.py + :linenos: + +.. literalinclude:: ../examples/charlcd_rgb_simpletest.py + :caption: examples/charlcd_rgb_simpletest.py + :linenos: + +.. literalinclude:: ../examples/charlcd_I2C_simpletest.py + :caption: examples/charlcd_I2C_simpletest.py + :linenos: + +.. literalinclude:: ../examples/charlcd_SPI_simpletest.py + :caption: examples/charlcd_SPI_simpletest.py + :linenos: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9fa3f44 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,47 @@ +.. 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 + + Adafruit Character LCDs + +.. toctree:: + :caption: Other Links + + Download + CircuitPython Reference Documentation + CircuitPython Support Forum + Discord Chat + Adafruit Learning System + Adafruit Blog + Adafruit Store + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/examples/hello_CircuitPython_I2C.py b/examples/charlcd_I2C_simpletest.py similarity index 100% rename from examples/hello_CircuitPython_I2C.py rename to examples/charlcd_I2C_simpletest.py diff --git a/examples/hello_CircuitPython_SPI.py b/examples/charlcd_SPI_simpletest.py similarity index 100% rename from examples/hello_CircuitPython_SPI.py rename to examples/charlcd_SPI_simpletest.py diff --git a/examples/hello_CircuitPython.py b/examples/charlcd_mono_simpletest.py similarity index 100% rename from examples/hello_CircuitPython.py rename to examples/charlcd_mono_simpletest.py diff --git a/examples/rgb_hello_CircuitPython.py b/examples/charlcd_rgb_simpletest.py similarity index 100% rename from examples/rgb_hello_CircuitPython.py rename to examples/charlcd_rgb_simpletest.py diff --git a/requirements.txt b/requirements.txt index 8b13789..c47d35a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1 +1 @@ - +adafruit-circuitpython-bus-device