Fix docs build by splitting out support matrix

tannewt · tannewt · commit adf68ba2cc02 · 2023-10-20T13:27:02.000-07:00
diff --git 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
@@ -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
@@ -56,10 +56,6 @@ Specifically useful documentation when starting out:
 - `CircuitPython Essentials <https://learn.adafruit.com/circuitpython-essentials>`__
 - `Example Code <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/CircuitPython_Essentials>`__
 
-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 <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ has free code search for public repos like CircuitPython. So, visit `sourcegraph.com/github.com/adafruit/circuitpython <https://sourcegraph.com/github.com/adafruit/circuitpython>`_ to search the CircuitPython codebase online.
-
 Contributing
 ------------
 
diff --git a/conf.py b/conf.py
@@ -218,12 +218,12 @@ def autoapi_prepare_jinja_env(jinja_env):
                     "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 @@ def autoapi_prepare_jinja_env(jinja_env):
 # 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
@@ -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 <https://adafruit.com>`_ has many
+excellent tutorials available through the
+`Adafruit Learning System <https://learn.adafruit.com/>`_.
+
+
+.. 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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,29 +84,29 @@ 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 ####
 
 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
diff --git 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
@@ -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 [micropython-lib]
 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
@@ -17,6 +17,10 @@ You can also type a regular expression as a filter.
 
     <p id="support-matrix-filter-block"><input placeholder="Filter the boards by available modules" id="support-matrix-filter" type="text"/><span id="support-matrix-filter-num">(all)</span></p>
 
+.. 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}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# CircuitPython port to Spresense #`
	`1`	`+# CXD56 (Spresense) #`
`2`	`2`
`3`	`3`	`This directory contains the port of CircuitPython to Spresense. It is a compact`
`4`	`4`	`development board based on Sony’s power-efficient multicore microcontroller`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`		`-# CircuitPython Port To The NXP i.MX RT10xx Series`
	`1`	`+# NXP i.MX RT10xx Series`
`2`	`2`
`3`	`3`	`This is a port of CircuitPython to the i.MX RT10xx series of chips.`