tweak doc & fix linting

Author: s-light

docs/conf.py

@@ -26,6 +26,7 @@
 # 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 = ["usb_cdc"]
 
 
 intersphinx_mapping = {

examples/nonblocking_serialinput_advanced.py

@@ -30,8 +30,6 @@
 
 def userinput_print_help():
     """Print Help."""
-    global runtime_print
-    global runtime_print_intervall
     text = (
         "you can change some things:\n"
         "- 'tr': toggle print runtime ({runtime_print})\n"
@@ -47,6 +45,7 @@ def userinput_print_help():
 
 def userinput_handling(input_string):
     """Check Input."""
+    # pylint: disable=global-statement
     global running
     global runtime_print
     global runtime_print_next
@@ -76,9 +75,8 @@ def userinput_handling(input_string):
 
 def main_update():
     """Do all the things your main code want's to do...."""
-    global runtime_print
+    # pylint: disable=global-statement
     global runtime_print_next
-    global runtime_print_intervall
 
     if runtime_print:
         if runtime_print_next < time.monotonic():

examples/nonblocking_serialinput_advanced_statusline.py

@@ -7,6 +7,16 @@
 
 """Simple Minimal example of CircuitPython_nonblocking_serialinput library usage."""
 
+# CircuitPython ignores the normal docstring - so we have to explicitly set it..
+__doc__ = """
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+| nonblocking_serialinput_advanced_class.py                        |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+| more at:                                                         |
+| https://github.com/s-light/CircuitPython_nonblocking_serialinput |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
 import time
 import sys
 import board
@@ -44,6 +54,7 @@ def userinput_print_help(self):
         """Print Help."""
         text = (
             "you can change some things:\n"
+            "- '?': about\n"
             "- 'tr': toggle print runtime ({runtime_print})\n"
             "- 'time set:???': set print runtime intervall ({runtime_print_intervall: > 7.2f}s)\n"
             "- 'exit'  stop program"
@@ -56,17 +67,19 @@ def userinput_print_help(self):
 
     def userinput_event_handling(self, input_string):
         """Handle user input."""
-        if "tr" in input_string:
+        if "?" in input_string:
+            self.my_input.print(__doc__)
+        elif "tr" in input_string:
             self.runtime_print = not self.runtime_print
-        if "time set" in input_string:
+        elif "time set" in input_string:
             self.my_input.print("time set:")
             value = nb_serialin.parse_value(input_string, "time set")
             if nb_serialin.is_number(value):
                 self.runtime_print_intervall = value
                 self.runtime_print_next = (
                     time.monotonic() + self.runtime_print_intervall
                 )
-        if "exit" in input_string:
+        elif "exit" in input_string:
             self.my_input.print("Stop Program running.")
             self.running = False
 

examples/nonblocking_serialinput_statusline_dev.py

@@ -10,8 +10,8 @@
 import time
 import board
 import digitalio
-import nonblocking_serialinput as nb_serialin
 import ansi_escape_code as terminal
+import nonblocking_serialinput as nb_serialin
 
 ##########################################
 # globals

nonblocking_serialinput.py

@@ -20,10 +20,11 @@
 
 **Software and Dependencies:**
 
-* Adafruit CircuitPython firmware `>= 7.0.0 for the supported boards.
-    <https://github.com/adafruit/circuitpython/releases>`_
-    * Core Module `usb_cdc:
+* Adafruit CircuitPython firmware
+    `>= 7.0.0 for the supported boards. <https://github.com/adafruit/circuitpython/releases>`_
+    * Core Module ` ``usb_cdc``
     <https://circuitpython.readthedocs.io/en/latest/shared-bindings/usb_cdc/index.html>`_
+* `CircuitPython_ansi_escape_code <https://github.com/s-light/CircuitPython_ansi_escape_code>`_
 """
 
 import time
@@ -42,7 +43,7 @@
 
 
 class NonBlockingSerialInput:
-    """Non Blocking Serial Input Class.
+    r"""Non Blocking Serial Input Class.
 
     This CircuitPython helper class can be used as non-blocking *drop-in* for the build
     in ``input()`` method.
@@ -54,7 +55,7 @@ class NonBlockingSerialInput:
     :param function input_handling_fn: function to call if there is one ore more
         fully received new lines. ``input_handling(input_string: string)``
         Default: None
-    :param function print_help_fn:function to call when a help text should be printed
+    :param function print_help_fn: function to call when a help text should be printed
         fully received new lines. ``print_help()``
         Default: None
     :param ~usb_cdc.Serial serial: serial connection object to use
@@ -76,10 +77,10 @@ class NonBlockingSerialInput:
     :param string, list line_end_custom: set custom line ends
         Default: None
     :param bool use_universal_line_end_basic: use a basic default set of line_ends
-        [`\n`, '\r', '\r\n']
+        ``['\n', '\r', '\r\n']``]
         Default: True
     :param bool use_universal_line_end_advanced:  use a advanced default set of line_ends
-        ['\v', '\f', '\x1c',...]
+        ``['\v', '\f', '\x1c',...]``
         Default: False
     :param bool verbose: print debugging information in some internal functions. Default to False
 
@@ -168,7 +169,7 @@ def echo_print(self):
 
     def print(self, *args, content=True):
         # def print(self, *args, end="\n"):
-        """
+        r"""
         Print information & variables to the connected serial.
 
         This is a *drop in replacement* for the global print function.
@@ -177,7 +178,7 @@ def print(self, *args, content=True):
 
         currently it is not supported to print without newline at  end.
 
-        :param object *args: things to print
+        :param object \*args: things to print
         """
         # :param bool end: line end character to print. Default: "\n"
         if self.echo or self.statusline:
@@ -280,11 +281,12 @@ def _buffer_handle_cursor_position(self):
 
     def input(self):
         """
-        Input.
+        Get oldest input if available.
 
-        get oldest input string if there is any available. Otherwise an emtpy string.
+        test
+        Otherwise an emtpy string.
 
-        :return string: if available oldest input_line. Otherwise `""`
+        :return string: if available oldest input_line. otherwise ``""``
         """
         try:
             result = self.input_list.pop(0)
@@ -395,7 +397,7 @@ def find_first_line_end(input_string, line_end_list=None, start=0):
     :param string input_string: input search
     :param list line_end_list: list with strings to search for.
     :param int start: start position for search. (default = 0)
-    :return int: index of first found line_end; `-1` if nothing is found.
+    :return int: index of first found line_end; ``-1`` if nothing is found.
     """
     result = None
     if line_end_list is None:
@@ -422,7 +424,7 @@ def splitlines_advanced(input_string, line_end_list=None):
     then splits at these points. the resulting list is returned.
     this also returns empty string segments.
     the search happens in the order of line_end_list.
-    if the string does not end with a line_end symbol this last part will be returned in `rest`
+    if the string does not end with a line_end symbol this last part will be returned in ``rest``
 
     :param string input_string: input to split
     :param list line_end_list: list with strings where the splitting should happen.
@@ -471,11 +473,12 @@ def parse_value(input_string, pre_text=""):
     """
     Parse Value from input_string.
 
-    known values are numbers (`float()` is used), None, True, False
+    known values are numbers (``float()`` is used), ``None``, ``True``, ``False``
 
     :param string input_string: input to parse
-    :param string pre_text: text at start of input_string to ignore. defaults to ""
-    :return float | None | True | False: parsed value
+    :param string pre_text: text at start of input_string to ignore. defaults to ``""``
+    :return: parsed value
+    :rtype: float, None, bool
     """
     value = None
     # strip pre_text