Merge branch 'main' into master

7 files changed, 243 insertions, 16 deletions

diff --git a/docs/README.md b/docs/README.md
index e98b46f67..19c81a2fa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,7 +5,7 @@ The latest documentation can be found at:
 http://circuitpython.readthedocs.io/en/latest/
 
 The documentation you see there is generated from the files in the whole tree:
-https://github.com/adafruit/circuitpython/tree/master
+https://github.com/adafruit/circuitpython/tree/main
 
 Building the documentation locally
 ----------------------------------
diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 6f87ecf79..2d52e988b 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -1,9 +1,11 @@
+.. role:: strike
+
 Design Guide
 ============
 
 This guide covers a variety of development practices for CircuitPython core and library APIs. These
 APIs are both `built-into CircuitPython
-<https://github.com/adafruit/circuitpython/tree/master/shared-bindings>`_ and those that are
+<https://github.com/adafruit/circuitpython/tree/main/shared-bindings>`_ and those that are
 `distributed on GitHub <https://github.com/search?utf8=%E2%9C%93&q=topic%3Acircuitpython&type=>`_
 and in the `Adafruit <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_ and `Community
 <https://github.com/adafruit/CircuitPython_Community_Bundle/>`_ bundles. Consistency with these
@@ -46,6 +48,41 @@ not have the ``adafruit_`` module or package prefix.
 
 Both should have the CircuitPython repository topic on GitHub.
 
+Terminology
+-----------
+
+As our Code of Conduct states, we strive to use "welcoming and inclusive
+language." Whether it is in documentation or in code, the words we use matter.
+This means we disfavor language that due to historical and social context can
+make community members and potential community members feel unwelcome.
+
+There are specific terms to avoid except where technical limitations require it.
+While specific cases may call for other terms, consider using these suggested
+terms first:
+
++--------------------+---------------------+
+| Preferred          | Deprecated          |
++====================+=====================+
+| Main (device)      | :strike:`Master`    |
++--------------------+---------------------+
+| Peripheral         | :strike:`Slave`     |
++--------------------+                     +
+| Sensor             |                     |
++--------------------+                     +
+| Secondary (device) |                     |
++--------------------+---------------------+
+| Denylist           | :strike:`Blacklist` |
++--------------------+---------------------+
+| Allowlist          | :strike:`Whitelist` |
++--------------------+---------------------+
+
+Note that "technical limitations" refers e.g., to the situation where an
+upstream library or URL has to contain those substrings in order to work.
+However, when it comes to documentation and the names of parameters and
+properties in CircuitPython, we will use alternate terms even if this breaks
+tradition with past practice.
+
+
 .. _lifetime-and-contextmanagers:
 
 Lifetime and ContextManagers
diff --git a/docs/library/index.rst b/docs/library/index.rst
index 6c2e576e7..f847ead0a 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -70,7 +70,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
-versions of CircuitPtyon.
+versions of CircuitPython.
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/porting.rst b/docs/porting.rst
index d28f56f47..db4ae7626 100644
--- a/docs/porting.rst
+++ b/docs/porting.rst
@@ -64,7 +64,7 @@ as a natural "TODO" list. An example minimal build list is shown below:
     CIRCUITPY_ROTARYIO = 0
     CIRCUITPY_RTC = 0
     CIRCUITPY_FREQUENCYIO = 0
-    CIRCUITPY_I2CSLAVE = 0
+    CIRCUITPY_I2CPERIPHERAL = 0
     CIRCUITPY_DISPLAYIO = 0       # Requires SPI, PulseIO (stub ok)
 
     # These modules are implemented in shared-module/ - they can be included in
diff --git a/docs/redirects.txt b/docs/redirects.txt
new file mode 100644
index 000000000..75965eff9
--- /dev/null
+++ b/docs/redirects.txt
@@ -0,0 +1,161 @@
+shared-bindings//__init__.rst shared-bindings//
+shared-bindings/_bleio/Adapter.rst shared-bindings/_bleio/#_bleio.Adapter
+shared-bindings/_bleio/Address.rst shared-bindings/_bleio/#_bleio.Address
+shared-bindings/_bleio/Attribute.rst shared-bindings/_bleio/#_bleio.Attribute
+shared-bindings/_bleio/BluetoothError.rst shared-bindings/_bleio/#_bleio.BluetoothError
+shared-bindings/_bleio/Characteristic.rst shared-bindings/_bleio/#_bleio.Characteristic
+shared-bindings/_bleio/CharacteristicBuffer.rst shared-bindings/_bleio/#_bleio.CharacteristicBuffer
+shared-bindings/_bleio/Connection.rst shared-bindings/_bleio/#_bleio.Connection
+shared-bindings/_bleio/ConnectionError.rst shared-bindings/_bleio/#_bleio.ConnectionError
+shared-bindings/_bleio/Descriptor.rst shared-bindings/_bleio/#_bleio.Descriptor
+shared-bindings/_bleio/PacketBuffer.rst shared-bindings/_bleio/#_bleio.PacketBuffer
+shared-bindings/_bleio/RoleError.rst shared-bindings/_bleio/#_bleio.RoleError
+shared-bindings/_bleio/ScanEntry.rst shared-bindings/_bleio/#_bleio.ScanEntry
+shared-bindings/_bleio/ScanResults.rst shared-bindings/_bleio/#_bleio.ScanResults
+shared-bindings/_bleio/SecurityError.rst shared-bindings/_bleio/#_bleio.SecurityError
+shared-bindings/_bleio/Service.rst shared-bindings/_bleio/#_bleio.Service
+shared-bindings/_bleio/UUID.rst shared-bindings/_bleio/#_bleio.UUID
+shared-bindings/_bleio/__init__.rst shared-bindings/_bleio/
+shared-bindings/_eve/__init__.rst shared-bindings/_eve/
+shared-bindings/_pew/PewPew.rst shared-bindings/_pew/#_pew.PewPew
+shared-bindings/_pew/__init__.rst shared-bindings/_pew/
+shared-bindings/_pixelbuf/PixelBuf.rst shared-bindings/_pixelbuf/#_pixelbuf.PixelBuf
+shared-bindings/_pixelbuf/__init__.rst shared-bindings/_pixelbuf/
+shared-bindings/_stage/Layer.rst shared-bindings/_stage/#_stage.Layer
+shared-bindings/_stage/Text.rst shared-bindings/_stage/#_stage.Text
+shared-bindings/_stage/__init__.rst shared-bindings/_stage/
+shared-bindings/aesio/AES.rst shared-bindings/aesio/#aesio.AES
+shared-bindings/aesio/__init__.rst shared-bindings/aesio/
+shared-bindings/analogio/AnalogIn.rst shared-bindings/analogio/#analogio.AnalogIn
+shared-bindings/analogio/AnalogOut.rst shared-bindings/analogio/#analogio.AnalogOut
+shared-bindings/analogio/__init__.rst shared-bindings/analogio/
+shared-bindings/audiobusio/I2SOut.rst shared-bindings/audiobusio/#audiobusio.I2SOut
+shared-bindings/audiobusio/PDMIn.rst shared-bindings/audiobusio/#audiobusio.PDMIn
+shared-bindings/audiobusio/__init__.rst shared-bindings/audiobusio/
+shared-bindings/audiocore/RawSample.rst shared-bindings/audiocore/#audiocore.RawSample
+shared-bindings/audiocore/WaveFile.rst shared-bindings/audiocore/#audiocore.WaveFile
+shared-bindings/audiocore/__init__.rst shared-bindings/audiocore/
+shared-bindings/audioio/AudioOut.rst shared-bindings/audioio/#audioio.AudioOut
+shared-bindings/audioio/__init__.rst shared-bindings/audioio/
+shared-bindings/audiomixer/Mixer.rst shared-bindings/audiomixer/#audiomixer.Mixer
+shared-bindings/audiomixer/MixerVoice.rst shared-bindings/audiomixer/#audiomixer.MixerVoice
+shared-bindings/audiomixer/__init__.rst shared-bindings/audiomixer/
+shared-bindings/audiomp3/MP3.rst shared-bindings/audiomp3/#audiomp3.MP3
+shared-bindings/audiomp3/__init__.rst shared-bindings/audiomp3/
+shared-bindings/audiopwmio/PWMAudioOut.rst shared-bindings/audiopwmio/#audiopwmio.PWMAudioOut
+shared-bindings/audiopwmio/__init__.rst shared-bindings/audiopwmio/
+shared-bindings/bitbangio/I2C.rst shared-bindings/bitbangio/#bitbangio.I2C
+shared-bindings/bitbangio/OneWire.rst shared-bindings/bitbangio/#bitbangio.OneWire
+shared-bindings/bitbangio/SPI.rst shared-bindings/bitbangio/#bitbangio.SPI
+shared-bindings/bitbangio/__init__.rst shared-bindings/bitbangio/
+shared-bindings/board/__init__.rst shared-bindings/board/
+shared-bindings/busio/I2C.rst shared-bindings/busio/#busio.I2C
+shared-bindings/busio/OneWire.rst shared-bindings/busio/#busio.OneWire
+shared-bindings/busio/Parity.rst shared-bindings/busio/#busio.Parity
+shared-bindings/busio/SPI.rst shared-bindings/busio/#busio.SPI
+shared-bindings/busio/UART.rst shared-bindings/busio/#busio.UART
+shared-bindings/busio/__init__.rst shared-bindings/busio/
+shared-bindings/countio/Counter.rst shared-bindings/countio/#countio.Counter
+shared-bindings/countio/__init__.rst shared-bindings/countio/
+shared-bindings/digitalio/DigitalInOut.rst shared-bindings/digitalio/#digitalio.DigitalInOut
+shared-bindings/digitalio/Direction.rst shared-bindings/digitalio/#digitalio.Direction
+shared-bindings/digitalio/DriveMode.rst shared-bindings/digitalio/#digitalio.DriveMode
+shared-bindings/digitalio/Pull.rst shared-bindings/digitalio/#digitalio.Pull
+shared-bindings/digitalio/__init__.rst shared-bindings/digitalio/
+shared-bindings/displayio/Bitmap.rst shared-bindings/displayio/#displayio.Bitmap
+shared-bindings/displayio/ColorConverter.rst shared-bindings/displayio/#displayio.ColorConverter
+shared-bindings/displayio/Display.rst shared-bindings/displayio/#displayio.Display
+shared-bindings/displayio/EPaperDisplay.rst shared-bindings/displayio/#displayio.EPaperDisplay
+shared-bindings/displayio/FourWire.rst shared-bindings/displayio/#displayio.FourWire
+shared-bindings/displayio/Group.rst shared-bindings/displayio/#displayio.Group
+shared-bindings/displayio/I2CDisplay.rst shared-bindings/displayio/#displayio.I2CDisplay
+shared-bindings/displayio/OnDiskBitmap.rst shared-bindings/displayio/#displayio.OnDiskBitmap
+shared-bindings/displayio/Palette.rst shared-bindings/displayio/#displayio.Palette
+shared-bindings/displayio/ParallelBus.rst shared-bindings/displayio/#displayio.ParallelBus
+shared-bindings/displayio/Shape.rst shared-bindings/displayio/#displayio.Shape
+shared-bindings/displayio/TileGrid.rst shared-bindings/displayio/#displayio.TileGrid
+shared-bindings/displayio/__init__.rst shared-bindings/displayio/
+shared-bindings/fontio/BuiltinFont.rst shared-bindings/fontio/#fontio.BuiltinFont
+shared-bindings/fontio/Glyph.rst shared-bindings/fontio/#fontio.Glyph
+shared-bindings/fontio/__init__.rst shared-bindings/fontio/
+shared-bindings/framebufferio/FramebufferDisplay.rst shared-bindings/framebufferio/#framebufferio.FramebufferDisplay
+shared-bindings/framebufferio/__init__.rst shared-bindings/framebufferio/
+shared-bindings/frequencyio/FrequencyIn.rst shared-bindings/frequencyio/#frequencyio.FrequencyIn
+shared-bindings/frequencyio/__init__.rst shared-bindings/frequencyio/
+shared-bindings/gamepad/GamePad.rst shared-bindings/gamepad/#gamepad.GamePad
+shared-bindings/gamepad/__init__.rst shared-bindings/gamepad/
+shared-bindings/gamepadshift/GamePadShift.rst shared-bindings/gamepadshift/#gamepadshift.GamePadShift
+shared-bindings/gamepadshift/__init__.rst shared-bindings/gamepadshift/
+shared-bindings/gnss/__init__.rst shared-bindings/gnss/
+shared-bindings/i2cperipheral/__init__.rst shared-bindings/i2cperipheral/
+shared-bindings/i2csecondary/__init__.rst shared-bindings/i2csecondary/
+shared-bindings/i2cslave/I2CSlave.rst shared-bindings/i2cperipheral/#i2cperipheral.I2CPeripheral
+shared-bindings/i2cslave/I2CSlaveRequest.rst shared-bindings/i2cperipheral/#i2cperipheral.I2CPeripheralRequest
+shared-bindings/math/__init__.rst shared-bindings/math/
+shared-bindings/microcontroller/Pin.rst shared-bindings/microcontroller/#microcontroller.Pin
+shared-bindings/microcontroller/Processor.rst shared-bindings/microcontroller/#microcontroller.Processor
+shared-bindings/microcontroller/RunMode.rst shared-bindings/microcontroller/#microcontroller.RunMode
+shared-bindings/microcontroller/__init__.rst shared-bindings/microcontroller/
+shared-bindings/multiterminal/__init__.rst shared-bindings/multiterminal/
+shared-bindings/neopixel_write/__init__.rst shared-bindings/neopixel_write/
+shared-bindings/network/__init__.rst shared-bindings/network/
+shared-bindings/nvm/ByteArray.rst shared-bindings/nvm/#nvm.ByteArray
+shared-bindings/nvm/__init__.rst shared-bindings/nvm/
+shared-bindings/os/__init__.rst shared-bindings/os/
+shared-bindings/protomatter/__init__.rst shared-bindings/protomatter/
+shared-bindings/ps2io/Ps2.rst shared-bindings/ps2io/#ps2io.Ps2
+shared-bindings/ps2io/__init__.rst shared-bindings/ps2io/
+shared-bindings/pulseio/PWMOut.rst shared-bindings/pulseio/#pulseio.PWMOut
+shared-bindings/pulseio/PulseIn.rst shared-bindings/pulseio/#pulseio.PulseIn
+shared-bindings/pulseio/PulseOut.rst shared-bindings/pulseio/#pulseio.PulseOut
+shared-bindings/pulseio/__init__.rst shared-bindings/pulseio/
+shared-bindings/random/__init__.rst shared-bindings/random/
+shared-bindings/rgbmatrix/RGBMatrix.rst shared-bindings/rgbmatrix/#rgbmatrix.RGBMatrix
+shared-bindings/rgbmatrix/__init__.rst shared-bindings/rgbmatrix/
+shared-bindings/rotaryio/IncrementalEncoder.rst shared-bindings/rotaryio/#rotaryio.IncrementalEncoder
+shared-bindings/rotaryio/__init__.rst shared-bindings/rotaryio/
+shared-bindings/rtc/RTC.rst shared-bindings/rtc/#rtc.RTC
+shared-bindings/rtc/__init__.rst shared-bindings/rtc/
+shared-bindings/samd/Clock.rst shared-bindings/samd/#samd.Clock
+shared-bindings/samd/__init__.rst shared-bindings/samd/
+shared-bindings/socket/__init__.rst shared-bindings/socket/
+shared-bindings/socket/socket.rst shared-bindings/socket/#socket.socket
+shared-bindings/storage/VfsFat.rst shared-bindings/storage/#storage.VfsFat
+shared-bindings/storage/__init__.rst shared-bindings/storage/
+shared-bindings/struct/__init__.rst shared-bindings/struct/
+shared-bindings/supervisor/Runtime.rst shared-bindings/supervisor/#supervisor.Runtime
+shared-bindings/supervisor/__init__.rst shared-bindings/supervisor/
+shared-bindings/terminalio/Terminal.rst shared-bindings/terminalio/#terminalio.Terminal
+shared-bindings/terminalio/__init__.rst shared-bindings/terminalio/
+shared-bindings/time/__init__.rst shared-bindings/time/
+shared-bindings/time/struct_time.rst shared-bindings/time/#time.struct_time
+shared-bindings/touchio/TouchIn.rst shared-bindings/touchio/#touchio.TouchIn
+shared-bindings/touchio/__init__.rst shared-bindings/touchio/
+shared-bindings/uheap/__init__.rst shared-bindings/uheap/
+shared-bindings/ulab/__init__.rst shared-bindings/ulab/
+shared-bindings/ulab/approx/__init__.rst shared-bindings/ulab/approx/
+shared-bindings/ulab/array.rst shared-bindings/ulab/#ulab.array
+shared-bindings/ulab/compare/__init__.rst shared-bindings/ulab/compare/
+shared-bindings/ulab/extras/__init__.rst shared-bindings/ulab/extras/
+shared-bindings/ulab/fft/__init__.rst shared-bindings/ulab/fft/
+shared-bindings/ulab/filter/__init__.rst shared-bindings/ulab/filter/
+shared-bindings/ulab/linalg/__init__.rst shared-bindings/ulab/linalg/
+shared-bindings/ulab/numerical/__init__.rst shared-bindings/ulab/numerical/
+shared-bindings/ulab/poly/__init__.rst shared-bindings/ulab/poly/
+shared-bindings/ulab/vector/__init__.rst shared-bindings/ulab/vector/
+shared-bindings/usb_hid/Device.rst shared-bindings/usb_hid/#usb_hid.Device
+shared-bindings/usb_hid/__init__.rst shared-bindings/usb_hid/
+shared-bindings/usb_midi/PortIn.rst shared-bindings/usb_midi/#usb_midi.PortIn
+shared-bindings/usb_midi/PortOut.rst shared-bindings/usb_midi/#usb_midi.PortOut
+shared-bindings/usb_midi/__init__.rst shared-bindings/usb_midi/
+shared-bindings/ustack/__init__.rst shared-bindings/ustack/
+shared-bindings/vectorio/Circle.rst shared-bindings/vectorio/#vectorio.Circle
+shared-bindings/vectorio/Polygon.rst shared-bindings/vectorio/#vectorio.Polygon
+shared-bindings/vectorio/Rectangle.rst shared-bindings/vectorio/#vectorio.Rectangle
+shared-bindings/vectorio/VectorShape.rst shared-bindings/vectorio/#vectorio.VectorShape
+shared-bindings/vectorio/__init__.rst shared-bindings/vectorio/
+shared-bindings/watchdog/WatchDogMode.rst shared-bindings/watchdog/#watchdog.WatchDogMode
+shared-bindings/watchdog/WatchDogTimer.rst shared-bindings/watchdog/#watchdog.WatchDogTimer
+shared-bindings/watchdog/__init__.rst shared-bindings/watchdog/
+shared-bindings/wiznet/WIZNET5K.rst shared-bindings/wiznet/#wiznet.WIZNET5K
+shared-bindings/wiznet/__init__.rst shared-bindings/wiznet/
diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py
index 02ef68349..4abf5b885 100644
--- a/docs/shared_bindings_matrix.py
+++ b/docs/shared_bindings_matrix.py
@@ -23,6 +23,7 @@
 
 import json
 import os
+import pathlib
 import re
 import subprocess
 import sys
@@ -30,17 +31,27 @@ import sys
 
 SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm']
 
+def get_circuitpython_root_dir():
+    """ The path to the root './circuitpython' directory
+    """
+    file_path = pathlib.Path(__file__).resolve()
+    root_dir = file_path.parent.parent
+
+    return root_dir
+
 def get_shared_bindings():
     """ Get a list of modules in shared-bindings based on folder names
     """
-    return [item for item in os.listdir("./shared-bindings")]
+    shared_bindings_dir = get_circuitpython_root_dir() / "shared-bindings"
+    return [item.name for item in shared_bindings_dir.iterdir()]
 
 
 def read_mpconfig():
     """ Open 'circuitpy_mpconfig.mk' and return the contents.
     """
     configs = []
-    with open("py/circuitpy_mpconfig.mk") as mpconfig:
+    cpy_mpcfg = get_circuitpython_root_dir() / "py" / "circuitpy_mpconfig.mk"
+    with open(cpy_mpcfg) as mpconfig:
         configs = mpconfig.read()
 
     return configs
@@ -120,7 +131,7 @@ def lookup_setting(settings, key, default=''):
         key = value[2:-1]
     return value
 
-def support_matrix_by_board():
+def support_matrix_by_board(use_branded_name=True):
     """ Compiles a list of the available core modules available for each
         board.
     """
@@ -129,20 +140,22 @@ def support_matrix_by_board():
     boards = dict()
     for port in SUPPORTED_PORTS:
 
-        port_dir = "ports/{}/boards".format(port)
-        for entry in os.scandir(port_dir):
+        port_dir = get_circuitpython_root_dir() / "ports" / port
+        for entry in (port_dir / "boards").iterdir():
             if not entry.is_dir():
                 continue
             board_modules = []
+            board_name = entry.name
 
-            settings = get_settings_from_makefile(f'ports/{port}', entry.name)
+            settings = get_settings_from_makefile(str(port_dir), entry.name)
 
-            with open(os.path.join(entry.path, "mpconfigboard.h")) as get_name:
-                board_contents = get_name.read()
-            board_name_re = re.search("(?<=MICROPY_HW_BOARD_NAME)\s+(.+)",
-                                      board_contents)
-            if board_name_re:
-                board_name = board_name_re.group(1).strip('"')
+            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:
diff --git a/docs/static/customstyle.css b/docs/static/customstyle.css
index 6c964b762..ce2140e70 100644
--- a/docs/static/customstyle.css
+++ b/docs/static/customstyle.css
@@ -9,7 +9,19 @@
     margin: 4px;
 }
 
+/* custom CSS to sticky the ' viewing outdated version'
+   warning
+*/
+.document > .admonition {
+    position: sticky;
+    top: 0px;
+    background-color: salmon;
+    z-index: 2;
+}
 
+body {
+    overflow-x: unset!important;
+}
 
 /* override table width restrictions */
 @media screen and (min-width: 767px) {
@@ -24,3 +36,7 @@
       overflow: visible !important;
    }
 }
+
+.strike {
+    text-decoration: line-through;
+}