Merge pull request #61 from lesamouraipourpre/docs-and-examples

Docs and examples. Improving documentation. 
For release purposes: No functionality was added.

Author: jposada202020

.pre-commit-config.yaml

@@ -27,6 +27,7 @@ repos:
 -   repo: local
     hooks:
     -   id: pylint_examples
+        require_serial: true
         name: pylint (examples code)
         description: Run pylint rules on "examples/*.py" files
         entry: /usr/bin/env bash -c

README.rst

@@ -1,4 +1,3 @@
-
 Introduction
 ============
 
@@ -15,6 +14,7 @@ Introduction
     :alt: Build Status
 
 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>`_
@@ -58,8 +58,8 @@ 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>`_.
+This is easily achieved by downloading the
+`Adafruit library and driver bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_.
 
 Usage Example
 =============

adafruit_character_lcd/character_lcd.py

@@ -17,7 +17,7 @@
 
 **Hardware:**
 
-"* `Adafruit Character LCDs <http://www.adafruit.com/category/63_96>`_"
+* `Adafruit Character LCDs <http://www.adafruit.com/category/63_96>`_
 
 **Software and Dependencies:**
 
@@ -620,9 +620,12 @@ class Character_LCD_RGB(Character_LCD):
     :param ~digitalio.DigitalInOut db7: The data line 7
     :param columns: The columns on the charLCD
     :param lines: The lines on the charLCD
-    :param ~pwmio.PWMOut, ~digitalio.DigitalInOut red: Red RGB Anode
-    :param ~pwmio.PWMOut, ~digitalio.DigitalInOut green: Green RGB Anode
-    :param ~pwmio.PWMOut, ~digitalio.DigitalInOut blue: Blue RGB Anode
+    :param red: Red RGB Anode
+    :type red: ~pwmio.PWMOut or ~digitalio.DigitalInOut
+    :param green: Green RGB Anode
+    :type green: ~pwmio.PWMOut or ~digitalio.DigitalInOut
+    :param blue: Blue RGB Anode
+    :type blue: ~pwmio.PWMOut or ~digitalio.DigitalInOut
     :param ~digitalio.DigitalInOut read_write: The rw pin. Determines whether to read to or
         write from the display. Not necessary if only writing to the display. Used on shield.
 

adafruit_character_lcd/character_lcd_i2c.py

@@ -15,7 +15,7 @@
 
 **Hardware:**
 
-"* `I2C / SPI character LCD backpack <https://www.adafruit.com/product/292>`_"
+* `I2C / SPI character LCD backpack <https://www.adafruit.com/product/292>`_
 
 **Software and Dependencies:**
 
@@ -36,8 +36,8 @@
 class Character_LCD_I2C(Character_LCD_Mono):
     # pylint: disable=too-few-public-methods, too-many-arguments
     """Character LCD connected to I2C/SPI backpack using its I2C connection.
-    This is a subclass of Character_LCD and implements all of the same
-    functions and functionality.
+    This is a subclass of `Character_LCD_Mono` and implements all of the
+    same functions and functionality.
 
     To use, import and initialise as follows:
 

adafruit_character_lcd/character_lcd_rgb_i2c.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 """
-`adafruit_character_lcd.character_lcd_i2c`
+`adafruit_character_lcd.character_lcd_rgb_i2c`
 ====================================================
 
 Module for using I2C with I2C RGB LCD Shield or I2C RGB LCD Pi Plate
@@ -15,17 +15,17 @@
 
 **Hardware:**
 
-"* `RGB LCD Shield Kit w/ 16x2 Character Display - Negative Display
-<https://www.adafruit.com/product/714>`_"
+* `RGB LCD Shield Kit w/ 16x2 Character Display - Negative Display
+  <https://www.adafruit.com/product/714>`_
 
-"* `RGB LCD Shield Kit w/ 16x2 Character Display - Positive Display
-<https://www.adafruit.com/product/716>`_"
+* `RGB LCD Shield Kit w/ 16x2 Character Display - Positive Display
+  <https://www.adafruit.com/product/716>`_
 
-"* `Adafruit RGB Negative 16x2 LCD+Keypad Kit for Raspberry Pi
-<https://www.adafruit.com/product/1110>`_"
+* `Adafruit RGB Negative 16x2 LCD+Keypad Kit for Raspberry Pi
+  <https://www.adafruit.com/product/1110>`_
 
-"* `Adafruit RGB Positive 16x2 LCD+Keypad Kit for Raspberry Pi
-<https://www.adafruit.com/product/1109>`_"
+* `Adafruit RGB Positive 16x2 LCD+Keypad Kit for Raspberry Pi
+  <https://www.adafruit.com/product/1109>`_
 
 **Software and Dependencies:**
 
@@ -46,7 +46,7 @@
 
 class Character_LCD_RGB_I2C(Character_LCD_RGB):
     """RGB Character LCD connected to I2C shield or Pi plate using I2C connection.
-    This is a subclass of Character_LCD_RGB and implements all of the same
+    This is a subclass of `Character_LCD_RGB` and implements all of the same
     functions and functionality.
 
     To use, import and initialise as follows:

adafruit_character_lcd/character_lcd_spi.py

@@ -15,7 +15,7 @@
 
 **Hardware:**
 
-"* `I2C / SPI character LCD backpack <https://www.adafruit.com/product/292>`_"
+* `I2C / SPI character LCD backpack <https://www.adafruit.com/product/292>`_
 
 **Software and Dependencies:**
 
@@ -35,7 +35,7 @@
 
 class Character_LCD_SPI(Character_LCD_Mono):  # pylint: disable=too-few-public-methods
     """Character LCD connected to I2C/SPI backpack using its SPI connection.
-    This is a subclass of Character_LCD and implements all of the same
+    This is a subclass of `Character_LCD_Mono` and implements all of the same
     functions and functionality.
 
     To use, import and initialise as follows:

docs/api.rst

@@ -1,4 +1,3 @@
-
 .. If you created a package, create one automodule per module in the package.
 
 .. automodule:: adafruit_character_lcd.character_lcd
@@ -7,8 +6,8 @@
 .. automodule:: adafruit_character_lcd.character_lcd_i2c
    :members:
 
-.. automodule:: adafruit_character_lcd.character_lcd_spi
+.. automodule:: adafruit_character_lcd.character_lcd_rgb_i2c
    :members:
 
-.. automodule:: adafruit_character_lcd.character_lcd_rgb_i2c
+.. automodule:: adafruit_character_lcd.character_lcd_spi
    :members:

docs/conf.py

@@ -23,7 +23,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 = ["micropython", "digitalio", "addfruit_bus_device"]
+autodoc_mock_imports = ["micropython", "board", "busio", "digitalio", "pwmio"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.4", None),
@@ -43,7 +43,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "Adafruit CIRCUITPYTHON_CHARLCD Library"
+project = "Adafruit CircuitPython_CharLCD Library"
 copyright = "2017 Brent Rubell"
 author = "Brent Rubell"
 
@@ -118,7 +118,7 @@
 html_favicon = "_static/favicon.ico"
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "AdafruitCIRCUITPYTHON_CHARLCDLibrarydoc"
+htmlhelp_basename = "AdafruitCircuitPython_CharLCDLibrarydoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -143,8 +143,8 @@
 latex_documents = [
     (
         master_doc,
-        "AdafruitCIRCUITPYTHON_CHARLCDLibrary.tex",
-        "Adafruit CIRCUITPYTHON_CHARLCD Library Documentation",
+        "AdafruitCircuitPython_CharLCDLibrary.tex",
+        "Adafruit CircuitPython_CharLCD Library Documentation",
         author,
         "manual",
     ),
@@ -157,8 +157,8 @@
 man_pages = [
     (
         master_doc,
-        "adafruitCIRCUITPYTHON_CHARLCDlibrary",
-        "Adafruit CIRCUITPYTHON_CHARLCD Library Documentation",
+        "adafruitCircuitPython_CharLCDlibrary",
+        "Adafruit CircuitPython_CharLCD Library Documentation",
         [author],
         1,
     )
@@ -172,10 +172,10 @@
 texinfo_documents = [
     (
         master_doc,
-        "AdafruitCIRCUITPYTHON_CHARLCDLibrary",
-        "Adafruit CIRCUITPYTHON_CHARLCD Library Documentation",
+        "AdafruitCircuitPython_CharLCDLibrary",
+        "Adafruit CircuitPython_CharLCD Library Documentation",
         author,
-        "AdafruitCIRCUITPYTHON_CHARLCDLibrary",
+        "AdafruitCircuitPython_CharLCDLibrary",
         "One line description of project.",
         "Miscellaneous",
     ),

docs/examples.rst

@@ -1,24 +1,77 @@
-Simple test
+Simple tests
 ------------
 
-Ensure your device works with this simple test.
+Ensure your device works with these simple tests.
+
+Mono
+====
 
 .. literalinclude:: ../examples/charlcd_mono_simpletest.py
     :caption: examples/charlcd_mono_simpletest.py
     :linenos:
 
+RGB
+===
+
 .. literalinclude:: ../examples/charlcd_rgb_simpletest.py
     :caption: examples/charlcd_rgb_simpletest.py
     :linenos:
 
+I2C Mono
+========
+
 .. literalinclude:: ../examples/charlcd_i2c_mono_simpletest.py
     :caption: examples/charlcd_i2c_mono_simpletest.py
     :linenos:
 
+I2C RGB
+=======
+
+.. literalinclude:: ../examples/charlcd_i2c_rgb_simpletest.py
+    :caption: examples/charlcd_i2c_rgb_simpletest.py
+    :linenos:
+
+SPI Mono
+========
+
 .. literalinclude:: ../examples/charlcd_spi_mono_simpletest.py
     :caption: examples/charlcd_spi_mono_simpletest.py
     :linenos:
 
+Keypad
+======
+
 .. literalinclude:: ../examples/charlcd_keypad_simpletest.py
     :caption: examples/charlcd_keypad_simpletest.py
     :linenos:
+
+Raspberry Pi Mono
+=================
+
+.. literalinclude:: ../examples/charlcd_rpi_mono_simpletest.py
+    :caption: examples/charlcd_rpi_mono_simpletest.py
+    :linenos:
+
+Raspberry Pi RGB
+================
+
+.. literalinclude:: ../examples/charlcd_rpi_rgb_simpletest.py
+    :caption: examples/charlcd_rpi_rgb_simpletest.py
+    :linenos:
+
+Other tests
+-----------
+
+Custom Character
+================
+
+.. literalinclude:: ../examples/charlcd_customcharacter.py
+    :caption: examples/charlcd_customcharacter.py
+    :linenos:
+
+Nyan Cat
+========
+
+.. literalinclude:: ../examples/charlcd_custom_character_nyan_cat.py
+    :caption: examples/charlcd_custom_character_nyan_cat.py
+    :linenos: