Merge remote-tracking branch 'adafruit/main' into robots.txt

10 files changed, 105 insertions, 55 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 2d52e988b..75825893a 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -421,7 +421,7 @@ SPI Example
           """Widget's one register."""
           with self.spi_device as spi:
               spi.write(b'0x00')
-              i2c.readinto(self.buf)
+              spi.readinto(self.buf)
           return self.buf[0]
 
 Use composition
@@ -462,7 +462,7 @@ like properties for state even if it sacrifices a bit of speed.
 Avoid allocations in drivers
 --------------------------------------------------------------------------------
 
-Although Python doesn't require managing memory, its still a good practice for
+Although Python doesn't require managing memory, it's still a good practice for
 library writers to think about memory allocations. Avoid them in drivers if
 you can because you never know how much something will be called. Fewer
 allocations means less time spent cleaning up. So, where you can, prefer
@@ -471,7 +471,7 @@ object with methods that read or write into the buffer instead of creating new
 objects. Unified hardware API classes such as `busio.SPI` are design to read and
 write to subsections of buffers.
 
-Its ok to allocate an object to return to the user. Just beware of causing more
+It's ok to allocate an object to return to the user. Just beware of causing more
 than one allocation per call due to internal logic.
 
 **However**, this is a memory tradeoff so do not do it for large or rarely used
@@ -485,6 +485,19 @@ struct.pack
 
 Use `struct.pack_into` instead of `struct.pack`.
 
+Use of MicroPython ``const()``
+--------------------------------------------------------------------------------
+The MicroPython ``const()`` feature, as discussed in `this forum post
+<https://forum.micropython.org/viewtopic.php?t=450>`_, and in `this issue thread
+<https://github.com/micropython/micropython/issues/573>`_, provides some
+optimizations that can be useful on smaller, memory constrained devices. However,
+when using ``const()``, keep in mind these general guide lines:
+
+- Always use via an import, ex: ``from micropython import const``
+- Limit use to global (module level) variables only.
+- If user will not need access to variable, prefix name with a leading
+  underscore, ex: ``_SOME_CONST``.
+
 Sensor properties and units
 --------------------------------------------------------------------------------
 
@@ -567,4 +580,4 @@ MicroPython compatibility
 --------------------------------------------------------------------------------
 
 Keeping compatibility with MicroPython isn't a high priority. It should be done
-when its not in conflict with any of the above goals.
+when it's not in conflict with any of the above goals.
diff --git a/docs/drivers.rst b/docs/drivers.rst
index 241415cc1..8855abbd2 100644
--- a/docs/drivers.rst
+++ b/docs/drivers.rst
@@ -12,7 +12,7 @@ Adafruit CircuitPython Library Bundle
 We provide a bundle of all our libraries to ease installation of drivers and
 their dependencies. The bundle is primarily geared to the Adafruit Express line
 of boards which feature a relatively large external flash. With Express boards,
-its easy to copy them all onto the filesystem. However, if you don't have
+it's easy to copy them all onto the filesystem. However, if you don't have
 enough space simply copy things over as they are needed.
 
 - The Adafruit bundles are available on GitHub: <https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases>.
diff --git a/docs/library/hashlib.rst b/docs/library/hashlib.rst
index 0205d5e6a..8e5ebc2d1 100644
--- a/docs/library/hashlib.rst
+++ b/docs/library/hashlib.rst
@@ -20,10 +20,10 @@ be implemented:
 * SHA1 - A previous generation algorithm. Not recommended for new usages,
   but SHA1 is a part of number of Internet standards and existing
   applications, so boards targeting network connectivity and
-  interoperatiability will try to provide this.
+  interoperability will try to provide this.
 
 * MD5 - A legacy algorithm, not considered cryptographically secure. Only
-  selected boards, targeting interoperatibility with legacy applications,
+  selected boards, targeting interoperability with legacy applications,
   will offer this.
 
 Constructors
diff --git a/docs/library/index.rst b/docs/library/index.rst
index f847ead0a..e91387242 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -21,7 +21,7 @@ standard Python library.
    You may need to change your code later if you rely
    on any non-standard functionality they currently provide.
 
-CircuitPython's goal long-term goalis that code written in CircuitPython
+CircuitPython's long-term goal is that code written in CircuitPython
 using Python standard libraries will be runnable on CPython without changes.
 
 Some libraries below are not enabled on CircuitPython builds with
@@ -69,7 +69,7 @@ CircuitPython/MicroPython-specific libraries
 --------------------------------------------
 
 Functionality specific to the CircuitPython/MicroPython implementation is available in
-the following libraries. These libraries may change signficantly or be removed in future
+the following libraries. These libraries may change significantly or be removed in future
 versions of CircuitPython.
 
 .. toctree::
diff --git a/docs/library/network.rst b/docs/library/network.rst
index bd32267fe..3bd41150d 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -71,7 +71,7 @@ parameter should be `id`.
        (password) required to access said service. There can be further
        arbitrary keyword-only parameters, depending on the networking medium
        type and/or particular device. Parameters can be used to: a)
-       specify alternative service identifer types; b) provide additional
+       specify alternative service identifier types; b) provide additional
        connection parameters. For various medium types, there are different
        sets of predefined/recommended parameters, among them:
 
diff --git a/docs/porting.rst b/docs/porting.rst
index db4ae7626..8d0262455 100644
--- a/docs/porting.rst
+++ b/docs/porting.rst
@@ -51,10 +51,15 @@ as a natural "TODO" list. An example minimal build list is shown below:
 .. code-block:: makefile
 
     # These modules are implemented in ports/<port>/common-hal:
-    CIRCUITPY_MICROCONTROLLER = 0 # Typically the first module to create
-    CIRCUITPY_DIGITALIO = 0       # Typically the second module to create
+
+    # Typically the first module to create
+    CIRCUITPY_MICROCONTROLLER = 0
+    # Typically the second module to create
+    CIRCUITPY_DIGITALIO = 0
+    # Other modules:
     CIRCUITPY_ANALOGIO = 0
     CIRCUITPY_BUSIO = 0
+    CIRCUITPY_COUNTIO = 0
     CIRCUITPY_NEOPIXEL_WRITE = 0
     CIRCUITPY_PULSEIO = 0
     CIRCUITPY_OS = 0
@@ -63,22 +68,34 @@ as a natural "TODO" list. An example minimal build list is shown below:
     CIRCUITPY_AUDIOIO = 0
     CIRCUITPY_ROTARYIO = 0
     CIRCUITPY_RTC = 0
+    CIRCUITPY_SDCARDIO = 0
+    CIRCUITPY_FRAMEBUFFERIO = 0
     CIRCUITPY_FREQUENCYIO = 0
     CIRCUITPY_I2CPERIPHERAL = 0
-    CIRCUITPY_DISPLAYIO = 0       # Requires SPI, PulseIO (stub ok)
+    # Requires SPI, PulseIO (stub ok):
+    CIRCUITPY_DISPLAYIO = 0
 
     # These modules are implemented in shared-module/ - they can be included in
     # any port once their prerequisites in common-hal are complete.
-    CIRCUITPY_BITBANGIO = 0       # Requires DigitalIO
-    CIRCUITPY_GAMEPAD = 0         # Requires DigitalIO
-    CIRCUITPY_PIXELBUF = 0        # Requires neopixel_write or SPI (dotstar)
-    CIRCUITPY_RANDOM = 0          # Requires OS
-    CIRCUITPY_STORAGE = 0         # Requires OS, filesystem
-    CIRCUITPY_TOUCHIO = 0         # Requires Microcontroller
-    CIRCUITPY_USB_HID = 0         # Requires USB
-    CIRCUITPY_USB_MIDI = 0        # Requires USB
-    CIRCUITPY_REQUIRE_I2C_PULLUPS = 0 # Does nothing without I2C
-    CIRCUITPY_ULAB = 0            # No requirements, but takes extra flash
+    # Requires DigitalIO:
+    CIRCUITPY_BITBANGIO = 0
+    # Requires DigitalIO
+    CIRCUITPY_GAMEPAD = 0
+    # Requires neopixel_write or SPI (dotstar)
+    CIRCUITPY_PIXELBUF = 0
+    # Requires OS
+    CIRCUITPY_RANDOM = 0
+    # Requires OS, filesystem
+    CIRCUITPY_STORAGE = 0
+    # Requires Microcontroller
+    CIRCUITPY_TOUCHIO = 0
+    # Requires USB
+    CIRCUITPY_USB_HID = 0
+    CIRCUITPY_USB_MIDI = 0
+    # Does nothing without I2C
+    CIRCUITPY_REQUIRE_I2C_PULLUPS = 0
+    # No requirements, but takes extra flash
+    CIRCUITPY_ULAB = 0
 
 Step 2: Init
 --------------
@@ -89,7 +106,7 @@ request a safe mode state which prevents the supervisor from running user code
 while still allowing access to the REPL and other resources.
 
 The core port initialization and reset methods are defined in
-``supervisor/port.c`` and should be the first to be implemented. Its required
+``supervisor/port.c`` and should be the first to be implemented. It's required
 that they be implemented in the ``supervisor`` directory within the port
 directory. That way, they are always in the expected place.
 
diff --git a/docs/rstjinja.py b/docs/rstjinja.py
index 3a08b2599..7ab92a979 100644
--- a/docs/rstjinja.py
+++ b/docs/rstjinja.py
@@ -6,18 +6,28 @@ def rstjinja(app, docname, source):
     Render our pages as a jinja template for fancy templating goodness.
     """
     # Make sure we're outputting HTML
-    if app.builder.format != 'html':
+    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:
         return
 
-    src = source[0]
+    src = rendered = source[0]
     print(docname)
-    rendered = app.builder.templates.render_string(
-        src, app.config.html_context
-    )
+
+    if app.builder.format == "html":
+        rendered = app.builder.templates.render_string(
+            src, app.config.html_context
+        )
+    else:
+        from sphinx.util.template import BaseRenderer
+        renderer = BaseRenderer()
+        rendered = renderer.render_string(
+            src,
+            app.config.html_context
+        )
+
     source[0] = rendered
 
 def setup(app):
diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py
index 7b96c14f2..f38c0b64a 100644
--- a/docs/shared_bindings_matrix.py
+++ b/docs/shared_bindings_matrix.py
@@ -28,6 +28,7 @@ import re
 import subprocess
 import sys
 
+from concurrent.futures import ThreadPoolExecutor
 
 SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm']
 
@@ -43,7 +44,7 @@ def get_shared_bindings():
     """ Get a list of modules in shared-bindings based on folder names
     """
     shared_bindings_dir = get_circuitpython_root_dir() / "shared-bindings"
-    return [item.name for item in shared_bindings_dir.iterdir()]
+    return [item.name for item in shared_bindings_dir.iterdir()] + ["ulab"]
 
 
 def read_mpconfig():
@@ -131,38 +132,46 @@ def lookup_setting(settings, key, default=''):
         key = value[2:-1]
     return value
 
+def all_ports_all_boards(ports=SUPPORTED_PORTS):
+    for port in ports:
+
+        port_dir = get_circuitpython_root_dir() / "ports" / port
+        for entry in (port_dir / "boards").iterdir():
+            if not entry.is_dir():
+                continue
+            yield (port, entry)
+
 def support_matrix_by_board(use_branded_name=True):
     """ Compiles a list of the available core modules available for each
         board.
     """
     base = build_module_map()
 
-    boards = dict()
-    for port in SUPPORTED_PORTS:
-
+    def support_matrix(arg):
+        port, entry = arg
         port_dir = get_circuitpython_root_dir() / "ports" / port
-        for entry in (port_dir / "boards").iterdir():
-            if not entry.is_dir():
-                continue
-            board_modules = []
+        settings = get_settings_from_makefile(str(port_dir), entry.name)
+
+        if use_branded_name:
+            with open(entry / "mpconfigboard.h") as get_name:
+                board_contents = get_name.read()
+            board_name_re = re.search(r"(?<=MICROPY_HW_BOARD_NAME)\s+(.+)",
+                                      board_contents)
+            if board_name_re:
+                board_name = board_name_re.group(1).strip('"')
+        else:
             board_name = entry.name
 
-            settings = get_settings_from_makefile(str(port_dir), entry.name)
-
-            if use_branded_name:
-                with open(entry / "mpconfigboard.h") as get_name:
-                    board_contents = get_name.read()
-                board_name_re = re.search(r"(?<=MICROPY_HW_BOARD_NAME)\s+(.+)",
-                                          board_contents)
-                if board_name_re:
-                    board_name = board_name_re.group(1).strip('"')
-
-            board_modules = []
-            for module in base:
-                key = f'CIRCUITPY_{module.upper()}'
-                if int(lookup_setting(settings, key, '0')):
-                    board_modules.append(base[module]['name'])
-            boards[board_name] = sorted(board_modules)
+        board_modules = []
+        for module in base:
+            key = f'CIRCUITPY_{module.upper()}'
+            if int(lookup_setting(settings, key, '0')):
+                board_modules.append(base[module]['name'])
+
+        return (board_name, sorted(board_modules))
+
+    executor = ThreadPoolExecutor(max_workers=os.cpu_count())
+    boards = dict(sorted(executor.map(support_matrix, all_ports_all_boards())))
 
     #print(json.dumps(boards, indent=2))
     return boards
diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst
index 09571afb6..e74067e28 100644
--- a/docs/supported_ports.rst
+++ b/docs/supported_ports.rst
@@ -17,3 +17,4 @@ is limited.
     ../ports/mimxrt10xx/README
     ../ports/nrf/README
     ../ports/stm/README
+    ../ports/esp32s2/README
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index 66bcc2764..45c637f34 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -13,7 +13,7 @@ When CircuitPython restarts it will create a fresh empty ``CIRCUITPY`` filesyste
 
 This often happens on Windows when the ``CIRCUITPY`` disk is not safely ejected
 before being reset by the button or being disconnected from USB. This can also
-happen on Linux and Mac OSX but its less likely.
+happen on Linux and Mac OSX but it's less likely.
 
 .. caution:: To erase and re-create ``CIRCUITPY`` (for example, to correct a corrupted filesystem),
     follow one of the procedures below. It's important to note that **any files stored on the**
@@ -43,7 +43,7 @@ ValueError: Incompatible ``.mpy`` file.
 
 This error occurs when importing a module that is stored as a ``mpy`` binary file
 (rather than a ``py`` text file) that was generated by a different version of
-CircuitPython than the one its being loaded into. Most versions are compatible
+CircuitPython than the one it's being loaded into. Most versions are compatible
 but, rarely they aren't. In particular, the ``mpy`` binary format changed between
 CircuitPython versions 1.x and 2.x, and will change again between 2.x and 3.x.