added pydocstyle and compliant docstrings to source and example code.

Author: bsatrom

.github/workflows/python-package.yml

@@ -32,6 +32,9 @@ jobs:
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 test/ notecard/ examples/ --count --ignore=E722,F401,F403,W503 --show-source --statistics
+    - name: Lint Docs with Pydocstyle
+      run: |
+        pydocstyle notecard/ examples/
     - name: Test with pytest
       run: |
         pytest

MAKEFILE

@@ -7,6 +7,7 @@ default: test
 venv: $(VENV_NAME)/bin/activate
 
 test: venv
+	${PYTHON} -m pydocstyle notecard/ examples/
 	${PYTHON} -m flake8 test/ notecard/ examples/ --count --ignore=E722,F401,F403,W503 --show-source --statistics
 	${PYTHON} -m pytest test --cov=notecard
 

examples/cpy-example.py

@@ -1,3 +1,8 @@
+"""note-python CircuitPython example.
+
+This file contains a complete working sample for using the note-python
+library on a CircuitPython device.
+"""
 import sys
 import time
 import notecard
@@ -13,12 +18,26 @@
 
 
 def NotecardExceptionInfo(exception):
+    """Construct a formatted Exception string.
+
+    Args:
+        exception (Exception): An exception object.
+
+    Returns:
+        string: a summary of the exception with line number and details.
+    """
     name = exception.__class__.__name__
     return sys.platform + ": " + name \
         + ": " + ' '.join(map(str, exception.args))
 
 
 def transactionTest(card):
+    """Submit a simple JSON-based request to the Notecard.
+
+    Args:
+        card (object): An instance of the Notecard class
+
+    """
     req = {"req": "card.status"}
     req["string"] = "string"
     req["bool"] = True
@@ -34,6 +53,7 @@ def transactionTest(card):
 
 
 def main():
+    """Connect to Notcard and run a transaction test."""
     print("Opening port...")
     try:
         if use_uart:

examples/i2c-example.py

@@ -1,3 +1,8 @@
+"""note-python I2C example.
+
+This file contains a complete working sample for using the note-python
+library with an I2C Notecard connection.
+"""
 import sys
 import os
 import time
@@ -14,12 +19,26 @@
 
 
 def NotecardExceptionInfo(exception):
+    """Construct a formatted Exception string.
+
+    Args:
+        exception (Exception): An exception object.
+
+    Returns:
+        string: a summary of the exception with line number and details.
+    """
     s1 = '{}'.format(sys.exc_info()[-1].tb_lineno)
     s2 = exception.__class__.__name__
     return "line " + s1 + ": " + s2 + ": " + ' '.join(map(str, exception.args))
 
 
 def transactionTest(card):
+    """Submit a simple JSON-based request to the Notecard.
+
+    Args:
+        card (object): An instance of the Notecard class
+
+    """
     req = {"req": "card.status"}
     req["string"] = "string"
     req["bool"] = True
@@ -35,6 +54,7 @@ def transactionTest(card):
 
 
 def main():
+    """Connect to Notcard and run a transaction test."""
     print("Opening port...")
     try:
         port = I2C("/dev/i2c-1")

examples/mpy-example.py

@@ -1,3 +1,8 @@
+"""note-python MicroPython example.
+
+This file contains a complete working sample for using the note-python
+library on a MicroPython device.
+"""
 import sys
 import time
 import notecard
@@ -13,12 +18,26 @@
 
 
 def NotecardExceptionInfo(exception):
+    """Construct a formatted Exception string.
+
+    Args:
+        exception (Exception): An exception object.
+
+    Returns:
+        string: a summary of the exception with line number and details.
+    """
     name = exception.__class__.__name__
     return sys.platform + ": " + name + ": " \
         + ' '.join(map(str, exception.args))
 
 
 def transactionTest(card):
+    """Submit a simple JSON-based request to the Notecard.
+
+    Args:
+        card (object): An instance of the Notecard class
+
+    """
     req = {"req": "card.status"}
     req["string"] = "string"
     req["bool"] = True
@@ -34,6 +53,7 @@ def transactionTest(card):
 
 
 def main():
+    """Connect to Notcard and run a transaction test."""
     print("Opening port...")
     try:
         if use_uart:

examples/rpi-example.py

@@ -1,3 +1,8 @@
+"""note-python Raspberry Pi example.
+
+This file contains a complete working sample for using the note-python
+library on a Raspberry Pi device.
+"""
 import sys
 import os
 import time
@@ -19,12 +24,26 @@
 
 
 def NotecardExceptionInfo(exception):
+    """Construct a formatted Exception string.
+
+    Args:
+        exception (Exception): An exception object.
+
+    Returns:
+        string: a summary of the exception with line number and details.
+    """
     s1 = '{}'.format(sys.exc_info()[-1].tb_lineno)
     s2 = exception.__class__.__name__
     return "line " + s1 + ": " + s2 + ": " + ' '.join(map(str, exception.args))
 
 
 def transactionTest(card):
+    """Submit a simple JSON-based request to the Notecard.
+
+    Args:
+        card (object): An instance of the Notecard class
+
+    """
     req = {"req": "card.status"}
     req["string"] = "string"
     req["bool"] = True
@@ -40,6 +59,7 @@ def transactionTest(card):
 
 
 def main():
+    """Connect to Notcard and run a transaction test."""
     print("Opening port...")
     try:
         if use_uart:

examples/serial-example.py

@@ -1,3 +1,8 @@
+"""note-python Serial example.
+
+This file contains a complete working sample for using the note-python
+library with a Serial Notecard connection.
+"""
 import sys
 import os
 import time
@@ -20,12 +25,26 @@
 
 
 def NotecardExceptionInfo(exception):
+    """Construct a formatted Exception string.
+
+    Args:
+        exception (Exception): An exception object.
+
+    Returns:
+        string: a summary of the exception with line number and details.
+    """
     s1 = '{}'.format(sys.exc_info()[-1].tb_lineno)
     s2 = exception.__class__.__name__
     return "line " + s1 + ": " + s2 + ": " + ' '.join(map(str, exception.args))
 
 
 def transactionTest(card):
+    """Submit a simple JSON-based request to the Notecard.
+
+    Args:
+        card (object): An instance of the Notecard class
+
+    """
     req = {"req": "card.status"}
     req["string"] = "string"
     req["bool"] = True
@@ -41,6 +60,7 @@ def transactionTest(card):
 
 
 def main():
+    """Connect to Notcard and run a transaction test."""
     print("Opening port...")
     try:
         if sys.platform == "linux" or sys.platform == "linux2":

notecard/__init__.py

@@ -1 +1,3 @@
+"""__init__ Module for note-python."""
+
 from .notecard import *

notecard/card.py

@@ -1,7 +1,22 @@
+"""card Fluent API Helper.
+
+This module contains helper methods for calling card.*
+Notecard API commands.
+"""
 import notecard
 
 
 def attn(card, mode=None, files=None, seconds=None):
+    """Configure interrupt detection between a host and Notecard.
+
+    Args:
+        mode (string): The attn mode to set.
+        files (array): A collection of notefiles to watch.
+        seconds (int): A timeout to use when arming attn mode.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -16,6 +31,11 @@ def attn(card, mode=None, files=None, seconds=None):
 
 
 def time(card):
+    """Retrieve the current time and date from the Notecard.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -24,6 +44,11 @@ def time(card):
 
 
 def status(card):
+    """Retrieve the status of the Notecard.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -32,6 +57,11 @@ def status(card):
 
 
 def temp(card):
+    """Retrieve the current temperature from the Notecard.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -40,6 +70,11 @@ def temp(card):
 
 
 def version(card):
+    """Retrieve firmware version] information from the Notecard.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -48,6 +83,17 @@ def version(card):
 
 
 def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
+    """Retrive current and historical voltage info from the Notecard.
+
+    Args:
+        hours (int): Number of hours to analyze.
+        offset (int): Number of hours to offset.
+        vmax (decimal): max voltage level to report.
+        vmin (decimal): min voltage level to report.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 
@@ -64,6 +110,14 @@ def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
 
 
 def wireless(card, mode=None):
+    """Retrive wireless modem info or customize modem behavior.
+
+    Args:
+        mode (string): The wireless module mode to set.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")
 

notecard/env.py

@@ -1,7 +1,20 @@
+"""env Fluent API Helper.
+
+This module contains helper methods for calling env.*
+Notecard API commands.
+"""
 import notecard
 
 
 def get(card, name=None):
+    """Perform an env.get request against a Notecard.
+
+    Args:
+        name (string): The name of an environment variable to get.
+
+    Returns:
+        string: The result of the Notecard request.
+    """
     if not isinstance(card, notecard.Notecard):
         raise Exception("Notecard object required")