Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ jobs:
name: stubs
path: circuitpython-stubs/dist/*
- name: Test Documentation Build (HTML)
run: sphinx-build -E -W -b html -D version="$CP_VERSION" -D release="$CP_VERSION" . _build/html
run: sphinx-build -E -W -j auto -b html -D version="$CP_VERSION" -D release="$CP_VERSION" . _build/html
- uses: actions/upload-artifact@v7
with:
name: docs-html
Expand Down
7 changes: 5 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,11 @@

# You can set these variables from the command line.
PYTHON = python3
SPHINXOPTS = -W --keep-going
SPHINXOPTS = -W --keep-going -j auto
SPHINXBUILD = sphinx-build
# -silent hides pdflatex's progress output, including the thousands of undefined-reference
# warnings from its first pass. Warnings left after the last pass, and errors, are still reported.
LATEXMKOPTS = -silent
PAPER =
# path to build the generated docs
BUILDDIR = _build
Expand Down Expand Up @@ -171,7 +174,7 @@ latex:
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
$(MAKE) -C $(BUILDDIR)/latex all-pdf LATEXMKOPTS="$(LATEXMKOPTS)"
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

# seems to be malfunctioning
Expand Down
8 changes: 6 additions & 2 deletions conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath("docs"))
sys.path.insert(0, os.path.abspath("tools"))
sys.path.insert(0, os.path.abspath("."))

import shared_bindings_matrix
Expand All @@ -45,11 +46,14 @@
# Grab the JSON values to use while building the module support matrix
# in 'shared-bindings/index.rst'

# The stubs must be built before we calculate the shared bindings matrix
# Building the stubs also saves the board data the support matrix needs, so the
# slow per-board collection runs only once. If that file is missing,
# support_matrix_by_board() collects the data itself.
subprocess.check_output(["make", "stubs"])
board_data = shared_bindings_matrix.read_board_data("circuitpython-stubs/board_data.json")

# modules_support_matrix = shared_bindings_matrix.support_matrix_excluded_boards()
modules_support_matrix = shared_bindings_matrix.support_matrix_by_board()
modules_support_matrix = shared_bindings_matrix.support_matrix_by_board(board_data=board_data)
modules_support_matrix_reverse = defaultdict(list)
for board, matrix_info in modules_support_matrix.items():
for module in matrix_info["modules"]:
Expand Down
22 changes: 20 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,23 @@ In `circuitpython/`, build the docs:

You'll find the index page at `_build/html/index.html`.

### Building the PDF

The PDF build also needs LaTeX and `rsvg-convert`. On Debian or Ubuntu, install them with:

sudo apt install latexmk librsvg2-bin texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra

Then build the PDF:

make latexpdf

You'll find it at `_build/latex/CircuitPython.pdf`.

`pdflatex`'s output is verbose, with thousands of inconsequential warnings, so it goes to
`_build/latex/CircuitPython.log` instead of the console. To see it on the console anyway:

make latexpdf LATEXMKOPTS=

### More flexibility

Running `make` by itself will list out the multiple doc generating commands available.
Expand All @@ -38,8 +55,9 @@ All commands will, by default, run with `-E` (forces a rebuild from scratch of d
# will turn OFF the force rebuild and make it doubly verbose when running
make html FORCE= VERBOSE="-v -v"

You can also pass other options to sphinx by using `SPHINXOPTS`.
You can also pass other options to sphinx by using `SPHINXOPTS`. It replaces the default
options, `-W --keep-going -j auto`, so include any of those you still want:

make html SPHINXOPTS="-T"
make html SPHINXOPTS="-W --keep-going -j auto -T"

For more flexibility and customization, take a look at the Makefile for all variables you can pass in and overwrite.
50 changes: 17 additions & 33 deletions tools/board_stubs/build_board_specific_stubs/board_stub_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,6 @@ def create_board_stubs(board_id, records, mappings, board_filename):
boards_file.write(f"Board stub for {mappings['board_name']}\n")
boards_file.write(f" - port: {mappings['port']}\n")
boards_file.write(f" - board_id: {board_id}\n")
boards_file.write(f" - NVM size: {mappings['nvm_size']}\n")
boards_file.write(f" - Included modules: {included_modules}\n")
boards_file.write(f" - Frozen libraries: {frozen_libraries}\n")
boards_file.write('"""\n\n')
Expand Down Expand Up @@ -261,20 +260,27 @@ def process(board_mappings, export_dir):
print(f" - {board}")


def build_stubs(circuitpython_dir, circuitpython_org_dir, export_dir, version="8.2.9"):
def build_stubs(
circuitpython_dir, circuitpython_org_dir, export_dir, version="8.2.9", board_data_path=None
):
if circuitpython_dir[-1] != "/":
circuitpython_dir = circuitpython_dir + "/"

sys.path.append(circuitpython_dir)
from docs import shared_bindings_matrix
from tools import shared_bindings_matrix

if not os.path.exists(export_dir):
os.makedirs(export_dir)

collected = shared_bindings_matrix.collect_board_data()
if board_data_path:
# conf.py reads this so it doesn't have to collect the same data again.
shared_bindings_matrix.write_board_data(board_data_path, collected)

libraries = {}
if circuitpython_org_dir is None:
libraries = shared_bindings_matrix.support_matrix_by_board(
use_branded_name=False, withurl=False
use_branded_name=False, withurl=False, board_data=collected
)
else:
with open(f"{circuitpython_org_dir}/_data/files.json") as libraries_file:
Expand Down Expand Up @@ -306,38 +312,16 @@ def build_stubs(circuitpython_dir, circuitpython_org_dir, export_dir, version="8

board_mappings[board]["pins_filename"] = pins_path

nvm_size = "Unknown"
with open(f"{port_path}/mpconfigport.h") as get_name:
port_contents = get_name.read()
port_nvm_re = re.search(
r"(?<=#define CIRCUITPY_INTERNAL_NVM_SIZE)\s+(.+)", port_contents
)
if port_nvm_re:
nvm_size = port_nvm_re.group(1).strip()

board_name = board
with open(f"{board_path}/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('"')

port_nvm_re = re.search(
r"(?<=#define CIRCUITPY_INTERNAL_NVM_SIZE)\s+(.+)", port_contents
)
if port_nvm_re:
nvm_size = port_nvm_re.group(1).strip()

nvm_size_re = re.search(r"^[0-9\(\) *]*$", nvm_size)
if nvm_size_re:
nvm_size = eval(nvm_size_re.group(0))

board_mappings[board]["board_name"] = board_name
board_mappings[board]["nvm_size"] = nvm_size
board_mappings[board]["board_name"] = collected[lookup]["branded_name"]
board_mappings[board]["libraries"] = libraries.get(board, None)

process(board_mappings, export_dir)


if __name__ == "__main__":
build_stubs("./", None, "circuitpython-stubs/board_definitions/")
build_stubs(
"./",
None,
"circuitpython-stubs/board_definitions/",
board_data_path="circuitpython-stubs/board_data.json",
)
3 changes: 1 addition & 2 deletions tools/board_stubs/circuitpython_setboard/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,13 +74,12 @@ def set_board():
# Board stub for ...
# - port: ...
# - board_id: ...
# - NVM size: ...
# - Included modules: ...
# - Frozen libraries: ...
#

lines = get_doc_or_exit(board).split("\n")
port = lines[2].split("-")[1].split(":")[1].strip()
port = lines[2].split(":", 1)[1].strip()

if looking_for not in board.name.lower() and looking_for not in port.lower():
continue
Expand Down
5 changes: 1 addition & 4 deletions tools/board_summaries.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,6 @@
#

import re
import sys

sys.path.append("../docs")

from shared_bindings_matrix import support_matrix_by_board

Expand Down Expand Up @@ -185,7 +182,7 @@ def write_csvs(rows=1000, present="1", absent="0"):
"frozen": frozen_incidence_matrix_csvs(s, rows=rows, present=present, absent=absent),
"pins": board_pins_matrix_csvs(s, rows=rows),
}
for key, values in csvs:
for key, values in csvs.items():
for i in range(len(values)):
filename = f"{key}_{i}.csv"
print(f"writing {filename}")
Expand Down
3 changes: 0 additions & 3 deletions tools/board_to_port.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,7 @@
# SPDX-License-Identifier: MIT

import sys
from pathlib import Path

docs = Path(__file__).parent.parent / "docs"
sys.path.append(str(docs))
from shared_bindings_matrix import get_board_mapping

board = sys.argv[1]
Expand Down
1 change: 0 additions & 1 deletion tools/build_board_info.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
sys.path.append("adabot")
import adabot.github_requests as github

sys.path.append("../docs")
from shared_bindings_matrix import (
SUPPORTED_PORTS,
support_matrix_by_board,
Expand Down
1 change: 0 additions & 1 deletion tools/build_release_files.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@
import json
import tomllib

sys.path.append("../docs")
from shared_bindings_matrix import get_settings_from_makefile

TOP = pathlib.Path(__file__).resolve().parent.parent
Expand Down
36 changes: 22 additions & 14 deletions tools/ci_set_matrix.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,6 @@
top_dir = tools_dir.parent

sys.path.insert(0, str(tools_dir / "adabot"))
sys.path.insert(0, str(top_dir / "docs"))

import build_board_info
from shared_bindings_matrix import (
Expand All @@ -49,9 +48,11 @@
"conf.py",
"docs",
"tests",
"tools/board_stubs/",
"tools/ci_changes_per_commit.py",
"tools/ci_check_duplicate_usb_vid_pid.py",
"tools/ci_set_matrix.py",
"tools/shared_bindings_matrix.py",
".github/workflows/run-tests.yml",
".github/workflows/run-zephyr-tests.yml",
".github/workflows/build-board-custom.yml",
Expand All @@ -66,30 +67,37 @@
}

PATTERN_DOCS = (
r"^(?:\.github|docs|extmod\/ulab)|"
r"^(?:(?:ports\/\w+\/bindings|shared-bindings)\S+\.c|tools\/extract_pyi\.py|\.readthedocs\.yml|conf\.py|requirements-doc\.txt)$|"
r"^(?:\.github|docs|extmod\/ulab|tools\/board_stubs\/)|"
r"^(?:(?:ports\/\w+\/bindings|shared-bindings)\S+\.c|tools\/extract_pyi\.py|tools\/shared_bindings_matrix\.py|\.readthedocs\.yml|conf\.py|requirements-doc\.txt)$|"
r"(?:-stubs|\.(?:md|MD|mk|rst|RST)|/Makefile)$"
)

GITHUB_MATRIX_LIMIT = 256

# The Zephyr tests build native_sim and the two bsim boards out of the shared sources, so a
# change confined to these cannot reach them: another port, a translation, a frozen library
# (this port has none), documentation, the unix test suite or the autogen PR workflow.
# (this port has none), documentation, the board stub tools, the unix test suite or the
# autogen PR workflow.
PATTERN_ZEPHYR_TESTS_IGNORE = re.compile(
r"^(?:docs|frozen|locale|tests)/|^ports/(?!zephyr-cp/)"
r"|^\.github/workflows/zephyr-autogen-pr\.yml$"
r"^(?:docs|frozen|locale|tests|tools/board_stubs)/|^ports/(?!zephyr-cp/)"
r"|^\.github/workflows/zephyr-autogen-pr\.yml$|^tools/shared_bindings_matrix\.py$"
)

# Files that can't affect the unix coverage tests: other ports and the documentation.
# The tests build nothing from ports/ except ports/unix. frozen/ is not on this list,
# because run-tests.py puts the frozen asyncio and Ticks libraries on the module search path.
PATTERN_TESTS_IGNORE = re.compile(r"^docs/|^ports/(?!unix/)")
# Files that can't affect the unix coverage tests: other ports and the documentation,
# including the docs' support matrix code and the board stub tools. The tests build nothing
# from ports/ except ports/unix. frozen/ is not on this list, because run-tests.py puts the
# frozen asyncio and Ticks libraries on the module search path.
PATTERN_TESTS_IGNORE = re.compile(
r"^(?:docs|tools/board_stubs)/|^ports/(?!unix/)|^tools/shared_bindings_matrix\.py$"
)

# Files that can't affect mpy-cross: ports, frozen libraries, the documentation and the tests.
# The board builds don't need the mpy-cross and mpy-cross-mac jobs. They use the mpy-cross
# that the scheduler job builds.
PATTERN_MPY_CROSS_IGNORE = re.compile(r"^(?:docs|frozen|ports|tests)/")
# Files that can't affect mpy-cross: ports, frozen libraries, the documentation (including
# the support matrix code and the board stub tools) and the tests. The board builds don't
# need the mpy-cross and mpy-cross-mac jobs. They use the mpy-cross that the scheduler job
# builds.
PATTERN_MPY_CROSS_IGNORE = re.compile(
r"^(?:docs|frozen|ports|tests|tools/board_stubs)/|^tools/shared_bindings_matrix\.py$"
)

# Zephyr boards don't use make, so their module tables can't be computed here. Each
# board's build writes autogen_board_info.toml next to its circuitpython.toml and that
Expand Down
Loading
Loading