Merge pull request #8185 from jepler/document-optional-types-functions

Document optional types & functions

docs/rstjinja.py

@@ -1,6 +1,15 @@
 # Derived from code on Eric Holscher's blog, found at:
 # https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
 
+import re
+
+def render_with_jinja(docname, source):
+    if "shared-bindings/support_matrix" in docname:
+        return True
+    if re.search('^\s+.. jinja$', source[0], re.M):
+        return True
+    return False
+
 def rstjinja(app, docname, source):
     """
     Render our pages as a jinja template for fancy templating goodness.
@@ -9,12 +18,12 @@ def rstjinja(app, docname, source):
     if app.builder.format not in ("html", "latex"):
         return
 
-    # we only want our one jinja template to run through this func
-    if "shared-bindings/support_matrix" not in docname:
+    # we only want specific files to run through this func
+    if not render_with_jinja(docname, source):
         return
 
     src = rendered = source[0]
-    print(docname)
+    print(f"rendering {docname} as jinja templates")
 
     if app.builder.format == "html":
         rendered = app.builder.templates.render_string(

docs/shared_bindings_matrix.py

@@ -69,28 +69,23 @@ ADDITIONAL_MODULES = {
     "array": "CIRCUITPY_ARRAY",
     # always available, so depend on something that's always 1.
     "builtins": "CIRCUITPY",
+    "builtins.pow3": "CIRCUITPY_BUILTINS_POW3",
+    "busio.SPI": "CIRCUITPY_BUSIO_SPI",
+    "busio.UART": "CIRCUITPY_BUSIO_UART",
     "collections": "CIRCUITPY_COLLECTIONS",
     "fontio": "CIRCUITPY_DISPLAYIO",
     "io": "CIRCUITPY_IO",
+    "keypad.KeyMatrix": "CIRCUITPY_KEYPAD_KEYMATRIX",
+    "keypad.Keys": "CIRCUITPY_KEYPAD_KEYS",
+    "keypad.ShiftRegisterKeys": "CIRCUITPY_KEYPAD_SHIFTREGISTERKEYS",
+    "os.getenv": "CIRCUITPY_OS_GETENV",
     "select": "MICROPY_PY_USELECT_SELECT",
-    "terminalio": "CIRCUITPY_DISPLAYIO",
     "sys": "CIRCUITPY_SYS",
+    "terminalio": "CIRCUITPY_DISPLAYIO",
     "usb": "CIRCUITPY_USB_HOST",
 }
 
-MODULES_NOT_IN_BINDINGS = [
-    "_asyncio",
-    "array",
-    "binascii",
-    "builtins",
-    "collections",
-    "errno",
-    "json",
-    "re",
-    "select",
-    "sys",
-    "ulab",
-]
+MODULES_NOT_IN_BINDINGS = [ "binascii", "errno", "json", "re", "ulab" ]
 
 FROZEN_EXCLUDES = ["examples", "docs", "tests", "utils", "conf.py", "setup.py"]
 """Files and dirs at the root of a frozen directory that should be ignored.
@@ -117,7 +112,7 @@ def get_bindings():
     bindings_modules = []
     for d in get_circuitpython_root_dir().glob("ports/*/bindings"):
         bindings_modules.extend(module.name for module in d.iterdir() if d.is_dir())
-    return shared_bindings_modules + bindings_modules + MODULES_NOT_IN_BINDINGS
+    return shared_bindings_modules + bindings_modules + MODULES_NOT_IN_BINDINGS + list(ADDITIONAL_MODULES.keys())
 
 
 def get_board_mapping():

shared-bindings/busio/SPI.c

@@ -52,7 +52,22 @@
 //|     `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
 //|     select line, often abbreviated `!CS` or `!SS`. (This is common because
 //|     multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
-//|     and therefore the hardware.)"""
+//|     and therefore the hardware.)
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["busio.SPI"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|
 //|     def __init__(
 //|         self,

shared-bindings/busio/UART.c

@@ -44,7 +44,22 @@
 // #define STREAM_DEBUG(...) mp_printf(&mp_plat_print __VA_OPT__(,) __VA_ARGS__)
 
 //| class UART:
-//|     """A bidirectional serial protocol"""
+//|     """A bidirectional serial protocol
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["busio.UART"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|
 //|     def __init__(
 //|         self,

shared-bindings/busio/__init__.c

@@ -77,6 +77,8 @@
 //|
 //| Tutorial for UART:
 //| https://learn.adafruit.com/circuitpython-essentials/circuitpython-uart-serial
+//|
+//| .. jinja
 //| """
 
 STATIC const mp_rom_map_elem_t busio_module_globals_table[] = {

shared-bindings/keypad/KeyMatrix.c

@@ -35,7 +35,22 @@
 #include "shared-bindings/util.h"
 
 //| class KeyMatrix:
-//|     """Manage a 2D matrix of keys with row and column pins."""
+//|     """Manage a 2D matrix of keys with row and column pins.
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["keypad.KeyMatrix"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|
 //|     def __init__(
 //|         self,

shared-bindings/keypad/Keys.c

@@ -35,7 +35,22 @@
 #include "shared-bindings/util.h"
 
 //| class Keys:
-//|     """Manage a set of independent keys."""
+//|     """Manage a set of independent keys.
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["keypad.Keys"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|
 //|     def __init__(
 //|         self,

shared-bindings/keypad/ShiftRegisterKeys.c

@@ -35,7 +35,22 @@
 #include "shared-bindings/util.h"
 
 //| class ShiftRegisterKeys:
-//|     """Manage a set of keys attached to an incoming shift register."""
+//|     """Manage a set of keys attached to an incoming shift register.
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["keypad.ShiftRegisterKeys"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|
 //|     def __init__(
 //|         self,

shared-bindings/keypad/__init__.c

@@ -89,6 +89,8 @@ const mp_obj_property_t keypad_generic_events_obj = {
 //|
 //| For more information about working with the `keypad` module in CircuitPython,
 //| see `this Learn guide <https://learn.adafruit.com/key-pad-matrix-scanning-in-circuitpython>`_.
+//|
+//| .. jinja
 //| """
 
 STATIC mp_rom_map_elem_t keypad_module_globals_table[] = {

shared-bindings/os/__init__.c

@@ -41,6 +41,8 @@
 //| """functions that an OS normally provides
 //|
 //| |see_cpython_module| :mod:`cpython:os`.
+//|
+//| .. jinja
 //| """
 //|
 //| import typing
@@ -88,7 +90,24 @@ MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd);
 //| def getenv(key: str, default: Optional[str] = None) -> Optional[str]:
 //|     """Get the environment variable value for the given key or return ``default``.
 //|
-//|     This may load values from disk so cache the result instead of calling this often."""
+//|     This may load values from disk so cache the result instead of calling this often.
+//|
+//|     On boards that do not support ``settings.toml`` reading in the core, this function will raise NotImplementedError.
+//|
+//|     .. raw:: html
+//|
+//|         <p>
+//|         <details>
+//|         <summary>Available on these boards</summary>
+//|         <ul>
+//|         {% for board in support_matrix_reverse["os.getenv"] %}
+//|         <li> {{ board }}
+//|         {% endfor %}
+//|         </ul>
+//|         </details>
+//|         </p>
+//|
+//|     """
 //|     ...
 //|
 STATIC mp_obj_t os_getenv(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {