diff --git a/BUILDING.md b/BUILDING.md index 1c47eb7b45..c5b4c5ae9b 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -48,7 +48,7 @@ To compile (or recompile) mpy-cross: make -C mpy-cross -# Building +## Building There a number of ports of CircuitPython! To build for your board, change to the appropriate ports directory and build. @@ -64,7 +64,7 @@ If you aren't sure what boards exist, have a peek in the boards subdirectory of If you have a fast computer with many cores, consider adding `-j` to your build flags, such as `-j17` on a 6-core 12-thread machine. -# Testing +## Testing If you are working on changes to the core language, you might find it useful to run the test suite. The test suite in the top level `tests` directory. It needs the unix port to run. @@ -84,7 +84,7 @@ A successful run will say something like 676 tests passed 30 tests skipped: buffered_writer builtin_help builtin_range_binop class_delattr_setattr cmd_parsetree extra_coverage framebuf1 framebuf16 framebuf2 framebuf4 framebuf8 framebuf_subclass mpy_invalid namedtuple_asdict non_compliant resource_stream schedule sys_getsizeof urandom_extra ure_groups ure_span ure_sub ure_sub_unmatched vfs_basic vfs_fat_fileio1 vfs_fat_fileio2 vfs_fat_more vfs_fat_oldproto vfs_fat_ramdisk vfs_userfs -# Debugging +## Debugging The easiest way to debug CircuitPython on hardware is with a JLink device, JLinkGDBServer, and an appropriate GDB. Instructions can be found at https://learn.adafruit.com/debugging-the-samd21-with-gdb @@ -99,7 +99,7 @@ Example: If your port/build includes `arm-none-eabi-gdb-py`, consider using it instead, as it can be used for better register debugging with https://github.com/bnahill/PyCortexMDebug -# Code Quality Checks +## Code Quality Checks We apply code quality checks using pre-commit. Install pre-commit once per system with diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 15b4cfc892..68e9cbeb7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,9 +38,9 @@ For SAMD21 debugging workflow tips check out [this learn guide](https://learn.ad Scott Shawcroft ([@tannewt](https://github.com/tannewt)) is the lead developer of CircuitPython and is sponsored by [Adafruit Industries LLC](https://adafruit.com). Scott is usually available during US West Coast working hours. Dan Halbert ([@dhalbert](https://github.com/dhalbert)) and -Kattni Rembor ([@kattni](https://github.com/kattni)) are also sponsored by [Adafruit Industries - LLC](https://adafruit.com) and are usually available during US East Coast daytime hours including -some weekends. +Jeff Epler ([@jepler](https://github.com/jepler)) are also sponsored by [Adafruit Industries +LLC](https://adafruit.com) and are usually available during US daytime hours including some +weekends. They are all reachable on [Discord](https://adafru.it/discord), GitHub issues and the [Adafruit support forum](https://forums.adafruit.com/viewforum.php?f=60). diff --git a/README.rst b/README.rst index 96ca69a50e..9175cfb4a2 100644 --- a/README.rst +++ b/README.rst @@ -56,10 +56,6 @@ Specifically useful documentation when starting out: - `CircuitPython Essentials `__ - `Example Code `__ -Code Search ------------- -GitHub doesn't currently support code search on forks. Therefore, CircuitPython doesn't have code search through GitHub because it is a fork of MicroPython. Luckily, `SourceGraph `_ has free code search for public repos like CircuitPython. So, visit `sourcegraph.com/github.com/adafruit/circuitpython `_ to search the CircuitPython codebase online. - Contributing ------------ diff --git a/conf.py b/conf.py index 11a589dd3b..938a71fa73 100644 --- a/conf.py +++ b/conf.py @@ -218,12 +218,12 @@ exclude_patterns = ["**/build*", "ports/nrf/usb", "ports/raspberrypi/sdk", "ports/raspberrypi/lib", - "ports/silabs", + "ports/silabs/gecko_sdk", + "ports/silabs/tools", "ports/stm/st_driver", "ports/stm/packages", "ports/stm/peripherals", "ports/stm/ref", - "ports/unix", "py", "shared/*", "shared-bindings/util.*", @@ -362,14 +362,21 @@ latex_elements = { # Additional stuff for the LaTeX preamble. #'preamble': '', # Include 3 levels of headers in PDF ToC -'preamble': '\setcounter{tocdepth}{2}', +'preamble': r''' +\setcounter{tocdepth}{2} +\hbadness=99999 +\hfuzz=20pt +\usepackage{pdflscape} +''', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'CircuitPython.tex', 'CircuitPython Documentation', + ("docs/pdf", 'CircuitPython.tex', 'CircuitPython Documentation', + 'CircuitPython Contributors', 'manual'), + ("shared-bindings/support_matrix", 'SupportMatrix.tex', 'Board Support Matrix', 'CircuitPython Contributors', 'manual'), ] diff --git a/docs/pdf.rst b/docs/pdf.rst new file mode 100644 index 0000000000..b60b0f77b2 --- /dev/null +++ b/docs/pdf.rst @@ -0,0 +1,60 @@ +:orphan: + +Adafruit CircuitPython API Reference +==================================== + +Welcome to the API reference documentation for Adafruit CircuitPython. +This contains low-level API reference docs which may link out to separate +*"getting started"* guides. `Adafruit `_ has many +excellent tutorials available through the +`Adafruit Learning System `_. + + +.. toctree:: + :maxdepth: 3 + + ../README.rst + libraries.rst + workflows + environment.rst + troubleshooting.rst + ../CONTRIBUTING + ../BUILDING + ../WEBUSB_README + supported_ports.rst + +Design and porting reference +---------------------------- + +.. toctree:: + :maxdepth: 1 + + design_guide + porting + common_hal + +API Reference +---------------------- + +.. toctree:: + :glob: + :maxdepth: 3 + + library/index.rst + ../shared-bindings/*/index + ../shared-bindings/help + + +.. toctree:: + :maxdepth: 1 + + reference/glossary.rst + ../CODE_OF_CONDUCT + ../docs/LICENSE + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst index fbe61e81ce..6112dd3e0e 100644 --- a/docs/supported_ports.rst +++ b/docs/supported_ports.rst @@ -12,10 +12,13 @@ is limited. :maxdepth: 2 ../ports/atmel-samd/README + ../ports/broadcom/README ../ports/cxd56/README ../ports/espressif/README ../ports/litex/README ../ports/mimxrt10xx/README ../ports/nrf/README ../ports/raspberrypi/README + ../ports/silabs/README ../ports/stm/README + ../ports/unix/README diff --git a/ports/broadcom/README.rst b/ports/broadcom/README.rst new file mode 100644 index 0000000000..10ff81711b --- /dev/null +++ b/ports/broadcom/README.rst @@ -0,0 +1,5 @@ +Broadcom +================== + +This port supports running CircuitPython bare-metal on Raspberry Pi single board +computers that utilize Broadcom system-on-chips. diff --git a/ports/cxd56/README.md b/ports/cxd56/README.md index d727722249..cccc2b6bac 100644 --- a/ports/cxd56/README.md +++ b/ports/cxd56/README.md @@ -1,4 +1,4 @@ -# CircuitPython port to Spresense # +# CXD56 (Spresense) # This directory contains the port of CircuitPython to Spresense. It is a compact development board based on Sony’s power-efficient multicore microcontroller diff --git a/ports/espressif/README.rst b/ports/espressif/README.rst index b8b0a097aa..6964d47a0e 100644 --- a/ports/espressif/README.rst +++ b/ports/espressif/README.rst @@ -1,4 +1,4 @@ -CircuitPython on Espressif SoCs +Espressif ======================================= This port adds the Espressif line of SoCs to CircuitPython. @@ -10,9 +10,11 @@ Support Status: :header: SoC, Status ESP32, "beta" + ESP32-H2, "alpha" ESP32-C3, "beta" + ESP32-C6, "alpha" ESP32-S2, "stable" - ESP32-S3, "beta" + ESP32-S3, "stable" How this port is organized: --------------------------------------- diff --git a/ports/mimxrt10xx/README.md b/ports/mimxrt10xx/README.md index fe7fd5ea69..c5039d03de 100644 --- a/ports/mimxrt10xx/README.md +++ b/ports/mimxrt10xx/README.md @@ -1,3 +1,3 @@ -# CircuitPython Port To The NXP i.MX RT10xx Series +# NXP i.MX RT10xx Series This is a port of CircuitPython to the i.MX RT10xx series of chips. diff --git a/ports/nrf/README.md b/ports/nrf/README.md index 88dd472738..481de89727 100644 --- a/ports/nrf/README.md +++ b/ports/nrf/README.md @@ -1,4 +1,4 @@ -# CircuitPython Port To The Nordic Semiconductor nRF52 Series +# Nordic Semiconductor nRF52 Series This is a port of CircuitPython to the Nordic Semiconductor nRF52 series of chips. diff --git a/ports/raspberrypi/README.rst b/ports/raspberrypi/README.rst index d6ad9b3335..4e615b9d92 100644 --- a/ports/raspberrypi/README.rst +++ b/ports/raspberrypi/README.rst @@ -15,4 +15,6 @@ Port Specific modules --------------------- .. toctree:: + ../../shared-bindings/cyw43/index + ../../shared-bindings/picodvi/index ../../shared-bindings/rp2pio/index diff --git a/ports/silabs/README.md b/ports/silabs/README.md index 3813104727..1307a95743 100644 --- a/ports/silabs/README.md +++ b/ports/silabs/README.md @@ -1,4 +1,4 @@ -# CircuitPython on EFR32 # +# Silicon Labs EFR32 # ![GitHub](https://img.shields.io/badge/Technology-Bluetooth_BLE-green) ![GitHub](https://img.shields.io/badge/CircuitPython-8.1.0--beta.0-green) @@ -84,11 +84,11 @@ Flash the project by using [Simplicity Commander](https://community.silabs.com/s ### Connecting to the Serial Console ### -Connect the devkit to the PC via the USB cable. The board uses serial for REPL access and debugging because the EFR32 chips has no USB support. +Connect the devkit to the PC via the USB cable. The board uses serial for REPL access and debugging because the EFR32 chips has no USB support. #### Windows #### -On Windows, we need to install a serial console e.g., PuTTY, MobaXterm. The JLink CDC UART Port can be found in the Device Manager. +On Windows, we need to install a serial console e.g., PuTTY, MobaXterm. The JLink CDC UART Port can be found in the Device Manager. #### Linux #### @@ -96,17 +96,17 @@ Open a terminal and issue the following command: ls /dev/ttyACM* -Then note down the correct name and substitute com-port-name in the following command with it: +Then note down the correct name and substitute `com-port-name` in the following command with it: screen /dev/'com-port-name' ### Using the REPL prompt ### -After flashing the firmware to the board, at your first connecting to the board, you might see a blank screen. Press enter and you should be presented with a Circuitpython prompt, >>>. If not, try to reset the board (see instructions below). +After flashing the firmware to the board, at your first connecting to the board, you might see a blank screen. Press enter and you should be presented with a Circuitpython prompt,`>>>`. If not, try to reset the board (see instructions below). You can now type in simple commands such as: - >>> print("Hello world!")  + >>> print("Hello world!") Hello world! If something goes wrong with the board, you can reset it. Pressing CTRL+D when the prompt is open performs a soft reset. @@ -119,13 +119,13 @@ Config serial: Tools > Options > Interpreter > Select MicroPython > Select Port ### Running CircuitPython scripts ### -At the boot stage, two scripts will be run (if not booting in safe mode). First, the file  boot.py  will be executed. The file **boot.py** can be used to perform the initial setup. Then, after boot.py has been completed, the file **code.py** will be executed.   +At the boot stage, two scripts will be run (if not booting in safe mode). First, the file `boot.py` will be executed. The file `boot.py` can be used to perform the initial setup. Then, after `boot.py` has been completed, the file `code.py` will be executed. -After code.py has finished executing, a REPL prompt will be presented on the serial port. Other files can also be executed by using the **Thonny** editors or using **Ampy** tool. +After code.py has finished executing, a REPL prompt will be presented on the serial port. Other files can also be executed by using the **Thonny** editors or using **Ampy** tool. ![Thonny](./res/Thonny.png) -With the boards which support USB mass storage, we can drag the files to the board file system. However, because the EFR32 boards don’t support USB mass storage, we need to use a tool like **Ampy** to copy the file to the board. You can use the latest version of **Ampy** and its  command to copy the module directories to the board. +With the boards which support USB mass storage, we can drag the files to the board file system. However, because the EFR32 boards don’t support USB mass storage, we need to use a tool like **Ampy** to copy the file to the board. You can use the latest version of **Ampy** and its command to copy the module directories to the board. Refer to the guide below for installing the **Ampy** tool: diff --git a/ports/silabs/license.md b/ports/silabs/license.md deleted file mode 100644 index 4833861a01..0000000000 --- a/ports/silabs/license.md +++ /dev/null @@ -1,21 +0,0 @@ -The MIT License (MIT) - -Copyright (c) 2013-2022 Damien P. George and others - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/ports/stm/README.md b/ports/stm/README.md index 5df9cedee2..f7a0b735ab 100644 --- a/ports/stm/README.md +++ b/ports/stm/README.md @@ -1,4 +1,4 @@ -# Circuitpython on STM32 # +# ST Microelectronics STM32 # This port brings the ST Microelectronics STM32 series of MCUs to Circuitpython. STM32 chips have a wide range of capability, from <$1 low power STM32F0s to dual-core STM32H7s running at 400+ MHz. Currently, only the F4, F7, and H7 families are supported, powered by the ARM Cortex M4 and M7 processors. diff --git a/ports/unix/README.md b/ports/unix/README.md index e15fd93b23..21661dc877 100644 --- a/ports/unix/README.md +++ b/ports/unix/README.md @@ -1,5 +1,5 @@ The Unix version ----------------- +================ The "unix" port requires a standard Unix-like environment with gcc and GNU make. This includes Linux, BSD, macOS, and Windows Subsystem for Linux. The @@ -46,7 +46,7 @@ Browse available modules at for more information about `mip`. External dependencies ---------------------- +===================== The `libffi` library and `pkg-config` tool are required. On Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`(includes toolchain and diff --git a/shared-bindings/support_matrix.rst b/shared-bindings/support_matrix.rst index e3428ac5bc..4318cde5ac 100644 --- a/shared-bindings/support_matrix.rst +++ b/shared-bindings/support_matrix.rst @@ -17,6 +17,10 @@ You can also type a regular expression as a filter.

(all)

+.. raw:: latex + + \begin{landscape} + .. rst-class:: support-matrix-table .. list-table:: :header-rows: 1 @@ -26,8 +30,10 @@ You can also type a regular expression as a filter. - Modules Available {% for key, value in support_matrix|dictsort %} - {{ '.. _' ~ key|replace(" ", "-") ~ ':' }} * - {{ key }} + + {{ '.. _' ~ key|replace(" ", "-") ~ ':' }} + - {{ ':py:mod:`' ~ value.modules|join("`, :py:mod:`") ~ '`' }} {% for module in value.frozen_libraries %}\ @@ -39,3 +45,7 @@ You can also type a regular expression as a filter. {% endfor %} {% endfor %} + +.. raw:: latex + + \end{landscape}