From dbbfd6695effce26fa5f507d1618cac8dfbb5779 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Fri, 30 Oct 2026 09:10:56 -0500 Subject: [PATCH] docs: link file mentions in package READMEs, AGENTS and CONTRIBUTING --- board_configs/desktop/README.md | 4 ++-- lib/audiodev/README.md | 8 ++++---- palettes/AGENTS.md | 2 +- palettes/CONTRIBUTING.md | 8 ++++---- pdwidgets/AGENTS.md | 4 ++-- pdwidgets/CONTRIBUTING.md | 8 ++++---- sayso/AGENTS.md | 4 ++-- sayso/README.md | 6 +++--- sayso/ROADMAP.md | 2 +- sayso/apps/spotify_remote/README.md | 20 ++++++++++---------- tools/README.md | 2 +- 11 files changed, 34 insertions(+), 34 deletions(-) diff --git a/board_configs/desktop/README.md b/board_configs/desktop/README.md index cce8bfe0..ce14167f 100644 --- a/board_configs/desktop/README.md +++ b/board_configs/desktop/README.md @@ -52,8 +52,8 @@ Applications instantiate an application coordinator only when they need one. Laz roles still come from `board_peripherals`. This bundle installs: -- `board_config.py` -- `board_peripherals.py` +- [`board_config.py`](board_config.py) +- [`board_peripherals.py`](board_peripherals.py) - `boarddev.py` - `audiodev/` (package) - `usdl2.py` diff --git a/lib/audiodev/README.md b/lib/audiodev/README.md index 0a12439f..b5f89da9 100644 --- a/lib/audiodev/README.md +++ b/lib/audiodev/README.md @@ -151,9 +151,9 @@ bytes in 8 KB chunks. [`pygame_audio.py`](pygame_audio.py) and [`web_audio.py`](web_audio.py) cannot run on MicroPython or CircuitPython at all (they need pygame-ce and Pyodide's `js` module), so a CPython-only idiom is -not a bug there. `pygame_audio.py` still uses the portable forms, because it -mirrors `sdl2_audio.py` closely enough to diff — see "Keep it in step with -`sdl2_audio.py`" below. `web_audio.py` shares nothing with them and stays as it is. +not a bug there. [`pygame_audio.py`](pygame_audio.py) still uses the portable forms, because it +mirrors [`sdl2_audio.py`](sdl2_audio.py) closely enough to diff — see "Keep it in step with +`sdl2_audio.py`" below. [`web_audio.py`](web_audio.py) shares nothing with them and stays as it is. Verify with the real interpreters rather than by inspection — CPython accepts everything above: @@ -622,7 +622,7 @@ thread. Do not make it synchronous. `PygamePCMOutput` mirrors `SDLPCMOutput` mechanism for mechanism: rate-based stall detection, the hardware-only prebuffer gate, the off-thread rebuild with a settle gap, the shadow buffer, and the same `recycles` / `lost_bytes` / -`requeued_bytes` counters. Every "do not simplify" rule in the `sdl2_audio.py` +`requeued_bytes` counters. Every "do not simplify" rule in the [`sdl2_audio.py`](sdl2_audio.py) section above applies here unchanged, and the constants carry the same names and values. diff --git a/palettes/AGENTS.md b/palettes/AGENTS.md index 64561cfe..d5f51446 100644 --- a/palettes/AGENTS.md +++ b/palettes/AGENTS.md @@ -2,7 +2,7 @@ - Run from `palettes/`: `PYTHONPATH=lib python3 -m unittest discover -s tests`, then `ruff check lib tests scripts`. These are the two checks CI runs. - `palettes` has its own version in `VERSION`, apart from the pydevices release. A merged change to `VERSION` and `CHANGELOG.md` tags `palettes-vX.Y.Z` and publishes `pydevices-palettes`; the import and mip name stay `palettes`. -- `lib/palettes/_*.py` is generated or static color data, and `palettes.toml` is generated by publishing automation. Don't edit either by hand. +- `lib/palettes/_*.py` is generated or static color data, and [`palettes.toml`](palettes.toml) is generated by publishing automation. Don't edit either by hand. - Docstrings use Google style with no Sphinx roles (no `:class:`); CI fails on one. - More in [CONTRIBUTING.md](CONTRIBUTING.md). - Examples follow the style in the [repo's AGENTS.md](../AGENTS.md): REUSE licence header, a docstring ending `Needs:`, `Run it:`, `Tested on:`, a settings block, a comment above each step, pygraphics rather than `framebuf`. diff --git a/palettes/CONTRIBUTING.md b/palettes/CONTRIBUTING.md index 71f86ddf..ec3798b4 100644 --- a/palettes/CONTRIBUTING.md +++ b/palettes/CONTRIBUTING.md @@ -18,9 +18,9 @@ code. | `tests/` | An import smoke test, plus contracts for depth, index and name order and cube size. | | `docs/` | The documentation site's source. | | [`scripts/generate_palette_screenshots.py`](scripts/generate_palette_screenshots.py) | Redraws the images under [`docs/images`](docs/images/). | -| `manifest.py` | The freeze manifest for [`lib/palettes`](lib/palettes/), for MicroPython and CircuitPython firmware builds. | -| `palettes.toml` | The PyScript gallery's file list. Generated by publishing automation; don't edit it by hand. | -| `pyproject.toml`, `VERSION` | The setuptools metadata and the package version. | +| [`manifest.py`](manifest.py) | The freeze manifest for [`lib/palettes`](lib/palettes/), for MicroPython and CircuitPython firmware builds. | +| [`palettes.toml`](palettes.toml) | The PyScript gallery's file list. Generated by publishing automation; don't edit it by hand. | +| [`pyproject.toml`](pyproject.toml), `VERSION` | The setuptools metadata and the package version. | ## Run the tests @@ -47,7 +47,7 @@ pip install -r docs/requirements.txt sphinx-build -W --keep-going -b html docs _site ``` -Read the Docs builds the same site from `.readthedocs.yaml`, with warnings as +Read the Docs builds the same site from [`.readthedocs.yaml`](.readthedocs.yaml), with warnings as errors. The API pages are generated from the docstrings when you build. ## Release diff --git a/pdwidgets/AGENTS.md b/pdwidgets/AGENTS.md index b5da4dbc..fc07c359 100644 --- a/pdwidgets/AGENTS.md +++ b/pdwidgets/AGENTS.md @@ -1,8 +1,8 @@ # AGENTS.md - Run from `pdwidgets/`. It imports `appdev`, `multimer`, `palettes` and `pygraphics` from source, so the bare test command fails with `No module named 'events'` unless they're installed. Put them on the path, with a pygraphics checkout at `$PYGRAPHICS`: `PYTHONPATH="lib:tests/stubs:../lib:../palettes/lib:$PYGRAPHICS/lib" python -m unittest discover -s tests`, then `ruff check lib tests scripts`. -- After you add or change a widget, run `python scripts/pdwidgets_widget_deps.py` to regenerate `lib/pdwidgets/widget-dependencies.md`. `lib/pdwidgets/icons/` and `pdwidgets.toml` are generated too; don't edit them by hand. +- After you add or change a widget, run `python scripts/pdwidgets_widget_deps.py` to regenerate [`lib/pdwidgets/widget-dependencies.md`](lib/pdwidgets/widget-dependencies.md). `lib/pdwidgets/icons/` and [`pdwidgets.toml`](pdwidgets.toml) are generated too; don't edit them by hand. - A `Label` takes `value=` and a `Button` takes `label=`. There is no `text=`. Callbacks are `callback(sender, event)`. - `pdwidgets` has its own version in `VERSION`, apart from the pydevices release; see [CONTRIBUTING.md](CONTRIBUTING.md#release) and its widget conventions. -- `tests/test_doc_examples.py` checks the Python blocks in the docs against the package, so a renamed argument fails there. +- [`tests/test_doc_examples.py`](tests/test_doc_examples.py) checks the Python blocks in the docs against the package, so a renamed argument fails there. - Examples follow the style in the [repo's AGENTS.md](../AGENTS.md): REUSE licence header, a docstring ending `Needs:`, `Run it:`, `Tested on:`, a settings block, a comment above each step, pygraphics rather than `framebuf`. diff --git a/pdwidgets/CONTRIBUTING.md b/pdwidgets/CONTRIBUTING.md index f8b4763d..e8b8fd82 100644 --- a/pdwidgets/CONTRIBUTING.md +++ b/pdwidgets/CONTRIBUTING.md @@ -18,9 +18,9 @@ the pieces fit. | `scripts/` | Icon generation, the widget dependency graph and the README screenshot. | | `tools/` | A render and event micro-benchmark, and a PNG smoke probe. | | `docs/` | The documentation site's source. | -| `manifest.py` | The freeze manifest for [`lib/pdwidgets`](lib/pdwidgets/), for firmware builds. | -| `pdwidgets.toml` | The PyScript gallery's file list. Generated by publishing automation; don't edit it by hand. | -| `pyproject.toml`, `VERSION` | The setuptools metadata and the package version. | +| [`manifest.py`](manifest.py) | The freeze manifest for [`lib/pdwidgets`](lib/pdwidgets/), for firmware builds. | +| [`pdwidgets.toml`](pdwidgets.toml) | The PyScript gallery's file list. Generated by publishing automation; don't edit it by hand. | +| [`pyproject.toml`](pyproject.toml), `VERSION` | The setuptools metadata and the package version. | ## Run the tests @@ -103,7 +103,7 @@ pip install -r docs/requirements.txt sphinx-build -W --keep-going -b html docs _site ``` -Read the Docs builds the same site from `.readthedocs.yaml`, with warnings as +Read the Docs builds the same site from [`.readthedocs.yaml`](.readthedocs.yaml), with warnings as errors. The API pages are generated from the docstrings when you build. ## Release diff --git a/sayso/AGENTS.md b/sayso/AGENTS.md index 6d6f14a3..f36fe822 100644 --- a/sayso/AGENTS.md +++ b/sayso/AGENTS.md @@ -1,8 +1,8 @@ # AGENTS.md -- Run from `sayso/`: `PYTHONPATH=lib python3 -m unittest discover -s tests`. The offline tests need no credentials; `tests/test_live.py` talks to Spotify and skips without `sayso.local.json`. +- Run from `sayso/`: `PYTHONPATH=lib python3 -m unittest discover -s tests`. The offline tests need no credentials; [`tests/test_live.py`](tests/test_live.py) talks to Spotify and skips without `sayso.local.json`. - Never commit `sayso.local.json`, `tokens.json` or `examples/write_examples.json`. - To test without a network, replace `sayso.transport.requests` with a mock that has `get`/`post` (and `put`/`delete` for writes) before you build `SpotifyClient`. - Spotify's Dev Mode removed `GET /users/{id}` and the legacy playlist track endpoints ([`PORTABILITY.md`](PORTABILITY.md)). Don't add `fetch_method` on `User`. -- `examples/*.py` and most `scripts/` need real credentials and a network; `scripts/endpoint_coverage.py` and `scripts/generate_object_specs.py` fetch Spotify's OpenAPI schema unless you pass a local path. +- `examples/*.py` and most `scripts/` need real credentials and a network; [`scripts/endpoint_coverage.py`](scripts/endpoint_coverage.py) and [`scripts/generate_object_specs.py`](scripts/generate_object_specs.py) fetch Spotify's OpenAPI schema unless you pass a local path. - Examples follow the style in the [repo's AGENTS.md](../AGENTS.md): REUSE licence header, a docstring ending `Needs:`, `Run it:`, `Tested on:`, a settings block, a comment above each step, pygraphics rather than `framebuf`. diff --git a/sayso/README.md b/sayso/README.md index bfc2ea9a..86057df6 100644 --- a/sayso/README.md +++ b/sayso/README.md @@ -115,7 +115,7 @@ Page-backed fields use `object_by_key` and a `page_method`: `User` and other non-fetchable types only expose fields present in the embedding response. Under February 2026 Dev Mode, `GET /users/{id}` is not available; use -`client.me()` for the authenticated user. See `PORTABILITY.md`. +`client.me()` for the authenticated user. See [`PORTABILITY.md`](PORTABILITY.md). When hydration or lazy page load fails, the object layer raises `HydrationError` with object type, endpoint, and Dev Mode hints. The original `TransportError` is @@ -370,7 +370,7 @@ Some playback controls require Spotify Premium and an active device. - **February 2026 Dev Mode** — several endpoints are removed or return 403 (for example `GET /users/{id}`, legacy `playlist_tracks`). Use `client.me()` for the current user and `playlist.items` for playlist entries. See - `PORTABILITY.md` for details. + [`PORTABILITY.md`](PORTABILITY.md) for details. -See `ROADMAP.md` for implemented areas, next steps, and open design questions. +See [`ROADMAP.md`](ROADMAP.md) for implemented areas, next steps, and open design questions. See `PORTABILITY.md` for CPython, MicroPython, and CircuitPython boundary notes. diff --git a/sayso/ROADMAP.md b/sayso/ROADMAP.md index 1337dbb9..c56282dc 100644 --- a/sayso/ROADMAP.md +++ b/sayso/ROADMAP.md @@ -12,7 +12,7 @@ transport helpers, read methods, selected write methods, examples, and live test - `Artist.albums` and `Playlist.items` wired to client page methods - Discovery scripts (`sayso_*_discovery.py`) for object-graph walkthroughs - Offline object-layer unit tests in [`tests/test_objects.py`](tests/test_objects.py) -- February 2026 Dev Mode API notes in `PORTABILITY.md` +- February 2026 Dev Mode API notes in [`PORTABILITY.md`](PORTABILITY.md) - `SpotifyObject.__str__()` pretty-prints raw object data for `print()` - Client Credentials auth - Authorization Code auth helpers consolidated in `sayso.auth` diff --git a/sayso/apps/spotify_remote/README.md b/sayso/apps/spotify_remote/README.md index 85b00f59..dbd381a5 100644 --- a/sayso/apps/spotify_remote/README.md +++ b/sayso/apps/spotify_remote/README.md @@ -15,16 +15,16 @@ MicroPython (Linux and Windows) under the PyDevices stack. | File | Role | |------|------| -| `main.py` | Entry point: auth, playback polling, event loop | -| `spotify_ctrl.py` | sayso wrapper (no LVGL) | -| `ui.py` | LVGL widgets; root screen via `scr = lv.screen_active()` | -| `config.py` | Tunable limits (cover-art cache size, library list size) | -| `artwork_cache.py` | Downloads and caches cover art from Spotify CDN URLs | -| `image_view.py` | Small LVGL cover-art view with a placeholder fallback | -| `genre_seeds.py` | Static genre preset list when the API seed endpoint is unavailable | -| `__main__.py` | `-m spotify_remote` entry point (runs the loop itself) | -| `local_speaker.py` | Optional earful Connect speaker in the same process | -| `keyboard_test.py` | PyDevices keyboard smoke test (LVGL textarea input) | +| [`main.py`](main.py) | Entry point: auth, playback polling, event loop | +| [`spotify_ctrl.py`](spotify_ctrl.py) | sayso wrapper (no LVGL) | +| [`ui.py`](ui.py) | LVGL widgets; root screen via `scr = lv.screen_active()` | +| [`config.py`](config.py) | Tunable limits (cover-art cache size, library list size) | +| [`artwork_cache.py`](artwork_cache.py) | Downloads and caches cover art from Spotify CDN URLs | +| [`image_view.py`](image_view.py) | Small LVGL cover-art view with a placeholder fallback | +| [`genre_seeds.py`](genre_seeds.py) | Static genre preset list when the API seed endpoint is unavailable | +| [`__main__.py`](__main__.py) | `-m spotify_remote` entry point (runs the loop itself) | +| [`local_speaker.py`](local_speaker.py) | Optional earful Connect speaker in the same process | +| [`keyboard_test.py`](keyboard_test.py) | PyDevices keyboard smoke test (LVGL textarea input) | ## Prerequisites diff --git a/tools/README.md b/tools/README.md index 31c0774c..b788b2a2 100644 --- a/tools/README.md +++ b/tools/README.md @@ -34,7 +34,7 @@ the sibling `gallery` integration repository. ## The package library -`libbuild.py` needs Python 3.11 or later, `git`, and `mpy-cross` +[`libbuild.py`](libbuild.py) needs Python 3.11 or later, `git`, and `mpy-cross` (`pip install mpy-cross`). From the repository root: ```bash