Merge pull request #8 from sommersoft/new_docs

Improve Ref Docs

Author: kattni

readthedocs.yml renamed to .readthedocs.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

.travis.yml

@@ -2,34 +2,49 @@
 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 <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>`_
 
 Compatible with CircuitPython Versions: 2.x
 
 Dependencies
 =============
 This driver depends on:
 
-* [Adafruit CircuitPython](https://github.com/adafruit/circuitpython "CircuitPython")
+* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
+
+I2C & SPI displays also depend on:
 
+* `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)
+`the Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_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 <https://github.com/adafruit/Adafruit_CircuitPython_CharLCD/releases>`_.
 #. 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 <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-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.

README.md renamed to README.rst

@@ -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
+  <http://www.adafruit.com/category/63_96>`_
+
+**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

adafruit_character_lcd/character_lcd.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
+  <http://www.adafruit.com/category/63_96>`_
+
+**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

adafruit_character_lcd/character_lcd_rgb.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