diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 6 | ||||
| -rw-r--r-- | docs/autoapi/templates/python/module.rst | 93 | ||||
| -rw-r--r-- | docs/c2rst.py | 31 | ||||
| -rw-r--r-- | docs/design_guide.rst | 43 | ||||
| -rw-r--r-- | docs/library/network.rst | 2 | ||||
| -rw-r--r-- | docs/porting.rst | 42 | ||||
| -rw-r--r-- | docs/redirects.txt | 161 | ||||
| -rw-r--r-- | docs/requirements.txt | 6 | ||||
| -rw-r--r-- | docs/shared_bindings_matrix.py | 252 | ||||
| -rw-r--r-- | docs/static/customstyle.css | 16 | ||||
| -rw-r--r-- | docs/supported_ports.rst | 13 |
11 files changed, 437 insertions, 228 deletions
diff --git a/docs/README.md b/docs/README.md index b01ae9d49..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 ---------------------------------- @@ -34,10 +34,10 @@ All commands will, by default, run with `-E` (forces a rebuild from scratch of d # will turn OFF the force rebuild make html FORCE= - + # will turn OFF the verbosity make html VERBOSE= - + # will turn OFF the force rebuild and make it doubly verbose when running make html FORCE= VERBOSE="-v -v" diff --git a/docs/autoapi/templates/python/module.rst b/docs/autoapi/templates/python/module.rst new file mode 100644 index 000000000..7ede6bdfd --- /dev/null +++ b/docs/autoapi/templates/python/module.rst @@ -0,0 +1,93 @@ +{% if not obj.display %} +:orphan: + +{% endif %} +:mod:`{{ obj.name }}` +======={{ "=" * obj.name|length }} + +.. py:module:: {{ obj.name }} + +{% if obj.docstring %} +.. autoapi-nested-parse:: + + {{ obj.docstring|prepare_docstring|indent(3) }} + +{% endif %} + +{% block subpackages %} +{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} +{% if visible_subpackages %} +.. toctree:: + :titlesonly: + :maxdepth: 3 + +{% for subpackage in visible_subpackages %} + {{ subpackage.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block submodules %} +{% set visible_submodules = obj.submodules|selectattr("display")|list %} +{% if visible_submodules %} + +.. toctree:: + :titlesonly: + :maxdepth: 1 + +{% for submodule in visible_submodules %} + {{ submodule.short_name }}/index.rst +{% endfor %} + + +{% endif %} +{% endblock %} +{% block content %} +{% if obj.all is not none %} +{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %} +{% elif obj.type is equalto("package") %} +{% set visible_children = obj.children|selectattr("display")|list %} +{% else %} +{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} +{% endif %} +{% if visible_children %} + +{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} +{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} +{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +{% block classes %} +{% if visible_classes %} +Classes +~~~~~~~ + +.. autoapisummary:: + +{% for klass in visible_classes %} + {{ klass.id }} +{% endfor %} + + +{% endif %} +{% endblock %} + +{% block functions %} +{% if visible_functions %} +Functions +~~~~~~~~~ + +.. autoapisummary:: + +{% for function in visible_functions %} + {{ function.id }} +{% endfor %} + + +{% endif %} +{% endblock %} +{% endif %} +{% for obj_item in visible_children %} +{{ obj_item.rendered|indent(0) }} +{% endfor %} +{% endif %} +{% endblock %} diff --git a/docs/c2rst.py b/docs/c2rst.py deleted file mode 100644 index 76489dca3..000000000 --- a/docs/c2rst.py +++ /dev/null @@ -1,31 +0,0 @@ -def c2rst(app, docname, source): - """ Pre-parse '.c' & '.h' files that contain rST source. - """ - # Make sure we're outputting HTML - if app.builder.format != 'html': - return - - fname = app.env.doc2path(docname) - if (not fname.endswith(".c") and - not fname.endswith(".h")): - #print("skipping:", fname) - return - - src = source[0] - - stripped = [] - for line in src.split("\n"): - line = line.strip() - if line == "//|": - stripped.append("") - elif line.startswith("//| "): - stripped.append(line[len("//| "):]) - stripped = "\r\n".join(stripped) - - rendered = app.builder.templates.render_string( - stripped, app.config.html_context - ) - source[0] = rendered - -def setup(app): - app.connect("source-read", c2rst) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 5d965f907..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 @@ -476,6 +513,8 @@ properties. +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``distance`` | float | centimeters | +-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``proximity`` | int | non-unit-specifc proximity values (monotonic but not actual distance) | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``light`` | float | non-unit-specific light levels (should be monotonic but is not lux) | +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``lux`` | float | SI lux | @@ -504,6 +543,8 @@ properties. +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``weight`` | float | grams (g) | +-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``sound_level`` | float | non-unit-specific sound level (monotonic but not actual decibels) | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ Adding native modules -------------------------------------------------------------------------------- diff --git a/docs/library/network.rst b/docs/library/network.rst index cdcc5f323..bd32267fe 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -247,7 +247,7 @@ Methods nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) .. method:: wlan.config('param') -.. method:: wlan.config(param=value, ...) + wlan.config(param=value, ...) Get or set general network interface parameters. These methods allow to work with additional parameters beyond standard IP configuration (as dealt with by diff --git a/docs/porting.rst b/docs/porting.rst index 6bb514458..db4ae7626 100644 --- a/docs/porting.rst +++ b/docs/porting.rst @@ -1,5 +1,5 @@ We love CircuitPython and would love to see it come to more microcontroller -platforms. With 3.0 we've reworked CircuitPython to make it easier than ever to +platforms. Since 3.0 we've reworked CircuitPython to make it easier than ever to add support. While there are some major differences between ports, this page covers the similarities that make CircuitPython what it is and how that core fits into a variety of microcontrollers. @@ -19,7 +19,7 @@ prepping file systems and automatically running user code on boot. In CircuitPython we've dubbed this component the supervisor because it monitors and facilitates the VMs which run user Python code. Porting involves the supervisor because many of the tasks it does while interfacing with the -hardware. Once its going though, the REPL works and debugging can migrate to a +hardware. Once complete, the REPL works and debugging can migrate to a Python based approach rather than C. The third core piece is the plethora of low level APIs that CircuitPython @@ -42,6 +42,44 @@ to the port's directory (in the top level until the ``ports`` directory is present). This includes the Makefile and any C library resources. Make sure these resources are compatible with the MIT License of the rest of the code! +Circuitpython has a number of modules enabled by default in +``py/circuitpy_mpconfig.mk``. Most of these modules will need to be disabled in +``mpconfigboard.mk`` during the early stages of a port in order for it to +compile. As the port progresses in module support, this list can be pruned down +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 + CIRCUITPY_ANALOGIO = 0 + CIRCUITPY_BUSIO = 0 + CIRCUITPY_NEOPIXEL_WRITE = 0 + CIRCUITPY_PULSEIO = 0 + CIRCUITPY_OS = 0 + CIRCUITPY_NVM = 0 + CIRCUITPY_AUDIOBUSIO = 0 + CIRCUITPY_AUDIOIO = 0 + CIRCUITPY_ROTARYIO = 0 + CIRCUITPY_RTC = 0 + CIRCUITPY_FREQUENCYIO = 0 + CIRCUITPY_I2CPERIPHERAL = 0 + CIRCUITPY_DISPLAYIO = 0 # Requires SPI, PulseIO (stub ok) + + # 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 + Step 2: Init -------------- Once your build is setup, the next step should be to get your clocks going as 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/requirements.txt b/docs/requirements.txt index 9edf6d328..51029bcba 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,5 @@ -sphinx==1.8.5 -recommonmark==0.5.0 +sphinx<3 +recommonmark==0.6.0 sphinxcontrib-svg2pdfconverter==0.1.0 +astroid +sphinx-autoapi diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index e327d6ec6..4abf5b885 100644 --- a/docs/shared_bindings_matrix.py +++ b/docs/shared_bindings_matrix.py @@ -23,62 +23,35 @@ import json import os +import pathlib import re +import subprocess +import sys -SUPPORTED_PORTS = ["atmel-samd", "nrf", "mimxrt10xx"] +SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm'] - -def parse_port_config(contents, chip_keyword=None): - """ Compile a dictionary of port-wide module configs, which may - be categorized by chipset. +def get_circuitpython_root_dir(): + """ The path to the root './circuitpython' directory """ - chip_fam = "all" - ifeq_found = False - port_config_results = {"all": []} - - chip_pattern = "" - if chip_keyword: - chip_pattern = ( - re.compile("(?<=ifeq\s\(\$\({}\)\,)(\w+)".format(chip_keyword)) - ) - - for line in contents: - if chip_keyword: - if not ifeq_found: - check_ifeq = chip_pattern.search(line) - if check_ifeq: - ifeq_found = True - chip_fam = check_ifeq.group(1) - #print("found chip:", chip_fam) - else: - ifeq_found = False - chip_fam = "all" - else: - if "endif" in line: - ifeq_found = False - chip_fam = "all" - - if "CIRCUITPY_" in line: - if chip_fam in port_config_results: - port_config_results[chip_fam].append(line.rstrip("\n")) - else: - port_config_results[chip_fam] = [line.rstrip("\n")] + file_path = pathlib.Path(__file__).resolve() + root_dir = file_path.parent.parent - #print(port_config_results) - return port_config_results + 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 @@ -98,7 +71,7 @@ def build_module_map(): for module in modules: full_name = module search_name = module.lstrip("_") - re_pattern = "CIRCUITPY_{}\s=\s(.+)".format(search_name.upper()) + re_pattern = "CIRCUITPY_{}\s*\??=\s*(.+)".format(search_name.upper()) find_config = re.findall(re_pattern, configs) if not find_config: continue @@ -117,171 +90,82 @@ def build_module_map(): "excluded": {} } - #print(base) return base +def get_settings_from_makefile(port_dir, board_name): + """ Invoke make in a mode which prints the database, then parse it for + settings. -def get_excluded_boards(base): - """ Cycles through each board's `mpconfigboard.mk` file to determine - if each module is included or not. Boards are selected by existence - in a port listed in `SUPPORTED_PORTS` (e.g. `/port/nrf/feather_52840`) - - Boards are further categorized by their respective chipset (SAMD21, - SAMD51, nRF52840, etc.) + This means that the effect of all Makefile directives is taken + into account, without having to re-encode the logic that sets them + in this script, something that has proved error-prone """ - modules = list(base.keys()) - - re_board_chip = None - chip_keyword = None - for port in SUPPORTED_PORTS: - # each port appears to use its own define for the chipset - if port in ["atmel-samd"]: - re_board_chip = re.compile("CHIP_FAMILY\s=\s(\w+)") - chip_keyword = "CHIP_FAMILY" - elif port in ["nrf"]: - re_board_chip = re.compile("MCU_VARIANT\s=\s(\w+)") - - port_dir = "ports/{}".format(port) - - port_config_contents = "" - with open(os.path.join(port_dir, "mpconfigport.mk")) as port_config: - port_config_contents = port_config.readlines() - port_config = parse_port_config(port_config_contents, chip_keyword) - - for entry in os.scandir(os.path.join(port_dir, "boards")): - if not entry.is_dir(): - continue - - contents = "" - board_dir = os.path.join(entry.path, "mpconfigboard.mk") - with open(board_dir) as board: - contents = board.read() - - board_chip = re_board_chip.search(contents) - #print(entry.name, board_chip.group(1)) - if not board_chip: - board_chip = "Unknown Chip" - else: - board_chip = board_chip.group(1) - - # add port_config results to contents - contents += "\n" + "\n".join(port_config["all"]) - if board_chip in port_config: - contents += "\n" + "\n".join(port_config[board_chip]) - - check_dependent_modules = dict() - for module in modules: - board_is_excluded = False - # check if board uses `SMALL_BUILD`. if yes, and current - # module is marked as `FULL_BUILD`, board is excluded - small_build = re.search("CIRCUITPY_SMALL_BUILD = 1", contents) - if small_build and base[module]["full_build"] == "1": - board_is_excluded = True - - # check if board uses `MINIMAL_BUILD`. if yes, and current - # module is marked as `DEFAULT_BUILD`, board is excluded - min_build = re.search("CIRCUITPY_MINIMAL_BUILD = 1", contents) - if min_build and base[module]["default_value"] == "CIRCUITPY_DEFAULT_BUILD": - board_is_excluded = True - - # check if module is specifically disabled for this board - re_pattern = r"CIRCUITPY_{}\s=\s(\w)".format(module.upper()) - find_module = re.search(re_pattern, contents) - if not find_module: - if base[module]["default_value"].isdigit(): - # check if default inclusion is off ('0'). if the board doesn't - # have it explicitly enabled, its excluded. - if base[module]["default_value"] == "0": - board_is_excluded = True - else: - # this module is dependent on another module. add it - # to the list to check after processing all other modules. - # only need to check exclusion if it isn't already excluded. - if (not board_is_excluded and - base[module]["default_value"] not in [ - "None", - "CIRCUITPY_DEFAULT_BUILD" - ]): - check_dependent_modules[module] = base[module]["default_value"] - else: - board_is_excluded = find_module.group(1) == "0" - - if board_is_excluded: - if board_chip in base[module]["excluded"]: - base[module]["excluded"][board_chip].append(entry.name) - else: - base[module]["excluded"][board_chip] = [entry.name] - - for module in check_dependent_modules: - depend_results = set() - - parents = check_dependent_modules[module].split("CIRCUITPY_") - parents = [item.strip(", ").lower() for item in parents if item] - - for parent in parents: - if parent in base: - if (board_chip in base[parent]["excluded"] and - entry.name in base[parent]["excluded"][board_chip]): - depend_results.add(False) - else: - depend_results.add(True) - - # only exclude the module if there were zero parents enabled - # as determined by the 'depend_results' set. - if not any(depend_results): - if board_chip in base[module]["excluded"]: - base[module]["excluded"][board_chip].append(entry.name) - else: - base[module]["excluded"][board_chip] = [entry.name] - - #print(json.dumps(base, indent=2)) - return base + contents = subprocess.run( + ["make", "-C", port_dir, f"BOARD={board_name}", "-qp", "print-CC"], + encoding="utf-8", + errors="replace", + stdout=subprocess.PIPE, + stderr=subprocess.PIPE + ) + # Make signals errors with exit status 2; 0 and 1 are "non-error" statuses + if contents.returncode not in (0, 1): + error_msg = ( + f"Invoking '{' '.join(contents.args)}' exited with " + f"{contents.returncode}: {contents.stderr}" + ) + raise RuntimeError(error_msg) + settings = {} + for line in contents.stdout.split('\n'): + m = re.match(r'^([A-Z][A-Z0-9_]*) = (.*)$', line) + if m: + settings[m.group(1)] = m.group(2) -def support_matrix_excluded_boards(): - """ Compiles a list of available modules, and which board definitions - do not include them. - """ - base = build_module_map() + return settings - return get_excluded_boards(base) +def lookup_setting(settings, key, default=''): + while True: + value = settings.get(key, default) + if not value.startswith('$'): + break + 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. """ base = build_module_map() - base_with_exclusions = get_excluded_boards(base) 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 - board_contents = "" - 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('"') - for module in base_with_exclusions.keys(): - #print(module) - board_has_module = True - if base_with_exclusions[module]["excluded"]: - for port in base_with_exclusions[module]["excluded"].values(): - #print(port) - if entry.name in port: - board_has_module = False + 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('"') - if board_has_module: - board_modules.append(base_with_exclusions[module]["name"]) + 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) #print(json.dumps(boards, indent=2)) return boards + +if __name__ == '__main__': + print(json.dumps(support_matrix_by_board(), indent=2)) 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; +} diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst index 9416a9c4f..09571afb6 100644 --- a/docs/supported_ports.rst +++ b/docs/supported_ports.rst @@ -1,14 +1,19 @@ Supported Ports ============================== -Adafruit's CircuitPython currently has limited support with a focus on supporting the Atmel SAMD -and ESP8266. +CircuitPython supports a number of microcontroller families. Support quality for each varies +depending on the active contributors for each port. + +Adafruit sponsored developers are actively contributing to atmel-samd, mimxrt10xx, nrf and stm +ports. They also maintain the other ports in order to ensure the boards build. Additional testing +is limited. .. toctree:: :maxdepth: 2 ../ports/atmel-samd/README + ../ports/cxd56/README + ../ports/litex/README ../ports/mimxrt10xx/README ../ports/nrf/README - ../ports/stm32f4/README - ../ports/cxd56/README + ../ports/stm/README |