docs: relative links for in-repo targets and linked file mentions

CONTRIBUTING.md

@@ -9,18 +9,18 @@ fix is a good first contribution.
 
 | Path | What's there |
 |---|---|
-| `build_mp.py` | The build command. |
+| [`build_mp.py`](build_mp.py) | The build command. |
 | `UPSTREAM` | The MicroPython commit the patches apply to. |
 | `modules.lock`, `deps.lock` | What gets fetched when it's missing, omnipython-lvgl included. |
-| `modules/` | The module manifest, `all/`, `tflite/` and `vision/` (esp-vision's), the modules linked or cloned, and the C modules that live only here: `audioif`, `cameraif`, `castif`, `displayif`, `h264enc`, `jpegio`, `mdns`, `pngio`, `ppa`, `tsmux`, `usbhost`. Each has its own README and tests. |
+| [`modules/`](modules) | The module manifest, `all/`, `tflite/` and `vision/` (esp-vision's), the modules linked or cloned, and the C modules that live only here: `audioif`, `cameraif`, `castif`, `displayif`, `h264enc`, `jpegio`, `mdns`, `pngio`, `ppa`, `tsmux`, `usbhost`. Each has its own README and tests. |
 | `modules/.omnipython-lvgl` | LVGL, its bindings and its ports, which `--modules lvgl` compiles: the sibling checkout, linked, or `modules.lock`'s commit, fetched. |
-| `patches/` | The patch series and `apply_patches.py`. |
-| `variants/`, `boards/` | Our variants and CircuitPython boards. |
-| `scripts/` | `exercise_build.sh`, `release_firmware.py`, `stage_firmware_page.py`, `serve_workbench.sh`, `freeze_list.py`, `update_provenance.py`. |
-| `.devcontainer/` | One dev container per port. |
-| `docs/` | The documentation site. |
+| [`patches/`](patches) | The patch series and `apply_patches.py`. |
+| [`variants/`](variants), [`boards/`](boards) | Our variants and CircuitPython boards. |
+| [`scripts/`](scripts) | `exercise_build.sh`, `release_firmware.py`, `stage_firmware_page.py`, `serve_workbench.sh`, `freeze_list.py`, `update_provenance.py`. |
+| [`.devcontainer/`](.devcontainer) | One dev container per port. |
+| [`docs/`](docs) | The documentation site. |
 
-The reference pages in [the docs](https://github.com/PyDevices/micropython-pydevices/blob/main/docs/index.md)
+The reference pages in [the docs](docs/index.md)
 describe what each of these does.
 
 ## Rules
@@ -43,7 +43,7 @@ python3 -m unittest test_provenance -v
 python3 -m unittest test_release_firmware test_stage_firmware_page -v
 ```
 
-Each module has its own workflow under `.github/workflows/`, named for it.
+Each module has its own workflow under [`.github/workflows/`](.github/workflows), named for it.
 
 ## Change a patch
 

README.md

@@ -46,6 +46,6 @@ For a board, name its port, board and variant, and the modules you want:
     --flash 16MB --modules displayif,pygraphics
 ```
 
-[Docs](https://github.com/PyDevices/micropython-pydevices/blob/main/docs/index.md) · [Examples](https://pydevices.github.io/gallery/gallery/) · [Roadmap](ROADMAP.md)
+[Docs](docs/index.md) · [Examples](https://pydevices.github.io/gallery/gallery/) · [Roadmap](ROADMAP.md)
 
 Made by [PyDevices](https://pydevices.com).

docs/get-started/install.md

@@ -30,7 +30,7 @@ installed at all, use [a codespace](../guides/build-in-a-codespace.md).
 
 ## Install what each port needs
 
-`build_mp.py` fetches the big pieces itself: MicroPython, the modules, ESP-IDF,
+[`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) fetches the big pieces itself: MicroPython, the modules, ESP-IDF,
 emsdk, the pico-sdk and picotool, and SDL2 for MinGW. What it can't fetch are
 your distribution's packages. On Debian or Ubuntu (WSL included):
 

docs/guides/add-a-board-variant.md

@@ -7,7 +7,7 @@ cache sizes and tick.
 
 ## An esp32 board
 
-On esp32, `build_mp.py` appends our ESP-IDF settings after the board's, so ours
+On esp32, [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) appends our ESP-IDF settings after the board's, so ours
 win. They come from files it finds by name, each used only if it exists, in
 this order:
 

docs/guides/build-in-a-codespace.md

@@ -37,7 +37,7 @@ Explorer, open `builds/` down to your build, right-click `firmware.bin` (or
 ## Try a webassembly build in workbench
 
 The webassembly container opens your build in workbench, the browser IDE.
-Build, then run [`scripts/serve_workbench.sh`](../../scripts/serve_workbench.sh): it downloads the newest workbench
+Build, then run [`scripts/serve_workbench.sh`](https://github.com/PyDevices/micropython-pydevices/blob/main/scripts/serve_workbench.sh): it downloads the newest workbench
 release, puts your `micropython.wasm` in it and serves it on port 8000, which
 the container forwards and your browser opens. Click the simulator button (the
 display icon) and the REPL that starts is your build.

docs/guides/build-on-windows.md

@@ -26,7 +26,7 @@ python build_mp.py --port windows --variant pydevices --modules all
 .\builds\windows\pydevices\micropython.exe
 ```
 
-That's all you type. `build_mp.py` finds MSYS2 in `C:\msys64` (set
+That's all you type. [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) finds MSYS2 in `C:\msys64` (set
 `MSYS2_ROOT` if it's elsewhere), puts its tools first on the build's `PATH`,
 and uses its `bash`. Left to `PATH`, `bash` from PowerShell is WSL's, which
 would run the build inside Linux. Without MSYS2 it stops and prints the install

docs/guides/flash-a-board.md

@@ -34,5 +34,5 @@ For a `.uf2`, mpftp copies it to the board's drive instead.
 
 ## After flashing
 
-pydevices' [Bringing up a board](https://github.com/PyDevices/pydevices/blob/main/docs/board-bringup.md)
+pydevices' [Bringing up a board](https://github.com/PyDevices/pydevices/blob/main/docs/guides/bring-up-a-board.md)
 takes a flashed board to one drawing on its own panel.

docs/guides/read-build-warnings.md

@@ -18,7 +18,7 @@ comes out as text and a log shows the colour codes raw. Nothing is broken.
   and still maps the old names.
 - `Component lockfile contents have changed`, a CMake warning that asks you to
   mention it in any issue. The build uses its own TinyUSB and a newer ESP-IDF
-  than upstream's lockfile records; `build_mp.py` puts the lockfile back
+  than upstream's lockfile records; [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) puts the lockfile back
   afterwards.
 - cmake's `Performing Test CMAKE_HAVE_LIBC_PTHREAD - Failed` and `Could NOT find
   Threads`.

docs/how-it-works/circuitpython.md

@@ -29,7 +29,7 @@ What differs is one function, and these are its parts.
   Python requirements in `deps/circuitpython-venv`.
 - **Our patches and boards go on first.** `patches/circuitpython/*.patch` are
   applied to `deps/circuitpython` and each `boards/circuitpython/<port>/<board>`
-  is linked into the port's `boards/`, once each; the build record lists the
+  is linked into the port's [`boards/`](https://github.com/PyDevices/micropython-pydevices/tree/main/boards), once each; the build record lists the
   patches. [The boards table](../reference/boards.md#circuitpython-boards) lists
   the boards.
 - **A module can ask espressif for ESP-IDF components.** CircuitPython's

docs/how-it-works/index.md

@@ -39,7 +39,7 @@ is the user's side of this.
 - Upstream is **pinned**. Moving `UPSTREAM` re-validates every patch.
 - Patches are justified in their headers. Never hand-edit a patched tree: change
   the patch and prepare again.
-- `build_mp.py` names no version and no setting. Pins move in the lock files,
+- [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) names no version and no setting. Pins move in the lock files,
   and esp32 settings live in sdkconfig fragments it finds by convention.
 - Publishing binaries is a separate decision from this source repository.
 

docs/index.md

@@ -2,7 +2,7 @@
 
 micropython-pydevices builds firmware: MicroPython-compatible and
 CircuitPython-compatible interpreters with the PyDevices C modules compiled in,
-for boards, desktops and the browser. One command, `build_mp.py`, does it.
+for boards, desktops and the browser. One command, [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py), does it.
 
 ## Get started
 

docs/reference/boards.md

@@ -23,7 +23,7 @@ For a board that isn't listed, see [Build for a board](../guides/build-for-a-boa
 
 ## Variants
 
-Our variants, in `variants/`.
+Our variants, in [`variants/`](https://github.com/PyDevices/micropython-pydevices/tree/main/variants).
 
 | Port | Variant | What it is |
 |---|---|---|

docs/reference/build-command.md

@@ -9,7 +9,7 @@
 
 Leave out `--port` and it asks for port, board and variant. On a port that has
 boards, leave out `--board` and it asks for that. `--variant` is always
-optional. Leave out `--modules` and it lists `modules/` and asks.
+optional. Leave out `--modules` and it lists [`modules/`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules) and asks.
 
 ## Options
 
@@ -18,7 +18,7 @@ optional. Leave out `--modules` and it lists `modules/` and asks.
 | `--interpreter` | `micropython` (the default) or `circuitpython`: CircuitPython-compatible firmware from CircuitPython's own ports and boards. |
 | `--port` | The port: `unix`, `windows`, `webassembly`, `esp32`, `rp2`. With `--interpreter circuitpython`, CircuitPython's own: `espressif`, `raspberrypi`, `unix` and the rest. |
 | `--board` | The board, by upstream's directory name. |
-| `--variant` | A variant of the board or port: upstream's, or one of ours in `variants/`. |
+| `--variant` | A variant of the board or port: upstream's, or one of ours in [`variants/`](https://github.com/PyDevices/micropython-pydevices/tree/main/variants). |
 | `--modules` | A comma list of short names, full paths, or `all`. See [Modules](modules.md). |
 | `--flash` | esp32 flash size, such as `16MB`. |
 | `--no-autosize` | esp32 and rp2: refuse instead of growing the firmware's share of flash. |
@@ -33,8 +33,8 @@ CircuitPython build they are part of the build record.
 | Variable | Default | Meaning |
 |---|---|---|
 | `OUT_DIR` | `builds/` | Where builds go. |
-| `VARIANTS_DIR` | `variants/` | Where our variants are found. |
-| `MODULES_DIR` | `modules/` | Where modules are found. |
+| `VARIANTS_DIR` | [`variants/`](https://github.com/PyDevices/micropython-pydevices/tree/main/variants) | Where our variants are found. |
+| `MODULES_DIR` | [`modules/`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules) | Where modules are found. |
 | `JOBS` | every core | The parallelism handed to make. |
 | `MSYS2_ROOT` | `C:\msys64` | On Windows, the MSYS2 whose make and MinGW gcc build the windows port. |
 | `IDF_TOOLS_PATH` | `~/.espressif` | Where an esp32 build installs ESP-IDF's toolchains. |

docs/reference/files.md

@@ -2,14 +2,14 @@
 
 | Path | What it is |
 |---|---|
-| [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) | The build command: [every option](build-command.md). It fills in `micropython/`, `modules/` and `deps/` if they're missing, prepares the MicroPython tree and runs the port's own `make`. |
+| [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) | The build command: [every option](build-command.md). It fills in `micropython/`, [`modules/`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules) and `deps/` if they're missing, prepares the MicroPython tree and runs the port's own `make`. |
 | [`UPSTREAM`](https://github.com/PyDevices/micropython-pydevices/blob/main/UPSTREAM) | The MicroPython commit everything applies to. |
-| [`modules.lock`](https://github.com/PyDevices/micropython-pydevices/blob/main/modules.lock) | The commits `build_mp.py` fetches when a module isn't there. It also pins [omnipython-lvgl](https://github.com/PyDevices/omnipython-lvgl), LVGL with its bindings and a port per interpreter: a build with `lvgl` (or `all`) fetches it into `modules/.omnipython-lvgl` and compiles the port for its interpreter. Beside sibling checkouts, these are links to those checkouts instead. |
-| [`deps.lock`](https://github.com/PyDevices/micropython-pydevices/blob/main/deps.lock) | The toolchains `build_mp.py` fetches: ESP-IDF, emsdk, SDL2 for MinGW, the TinyUSB the esp32 port builds on, and the ESP-IDF components CircuitPython builds ask for. It also pins CircuitPython, for `--interpreter circuitpython`. |
+| [`modules.lock`](https://github.com/PyDevices/micropython-pydevices/blob/main/modules.lock) | The commits [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) fetches when a module isn't there. It also pins [omnipython-lvgl](https://github.com/PyDevices/omnipython-lvgl), LVGL with its bindings and a port per interpreter: a build with `lvgl` (or `all`) fetches it into `modules/.omnipython-lvgl` and compiles the port for its interpreter. Beside sibling checkouts, these are links to those checkouts instead. |
+| [`deps.lock`](https://github.com/PyDevices/micropython-pydevices/blob/main/deps.lock) | The toolchains [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) fetches: ESP-IDF, emsdk, SDL2 for MinGW, the TinyUSB the esp32 port builds on, and the ESP-IDF components CircuitPython builds ask for. It also pins CircuitPython, for `--interpreter circuitpython`. |
 | [`provenance.json`](https://github.com/PyDevices/micropython-pydevices/blob/main/provenance.json) | The MicroPython pin and the checksum of every patch in [`patches/micropython/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/micropython) and [`patches/tinyusb/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/tinyusb). |
 | [`modules/`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules) | [`manifest.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/modules/manifest.py), the manifest every build freezes; `all/`; the modules, [linked or cloned](modules.md); and `.esp-vision/`, the pin for [esp-vision's modules](../how-it-works/esp-vision.md). |
-| [`patches/micropython/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/micropython) | Our patch series, `0001-…` to `0042-…` (there is no `0026`, whose fix moved into `patches/tinyusb/`), each justified in its own header. |
-| [`patches/tinyusb/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/tinyusb) | Patches to the TinyUSB the esp32 port builds on the S2, S3 and P4, which `build_mp.py` applies to `deps/espressif__tinyusb` (at its `deps.lock` tag) and builds in place of the port's own copy. |
+| [`patches/micropython/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/micropython) | Our patch series, `0001-…` to `0042-…` (there is no `0026`, whose fix moved into [`patches/tinyusb/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/tinyusb)), each justified in its own header. |
+| [`patches/tinyusb/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/tinyusb) | Patches to the TinyUSB the esp32 port builds on the S2, S3 and P4, which [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) applies to `deps/espressif__tinyusb` (at its `deps.lock` tag) and builds in place of the port's own copy. |
 | [`patches/micropython-lib/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/micropython-lib) | micropython-lib's own fixes from after the commit MicroPython's `lib/micropython-lib` points at. A firmware that freezes those packages, and a board whose `/lib` you fill from the submodule, both get them. |
 | [`patches/circuitpython/`](https://github.com/PyDevices/micropython-pydevices/tree/main/patches/circuitpython) | Our patches to CircuitPython, applied to `deps/circuitpython`. |
 | [`patches/apply_patches.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/patches/apply_patches.py) | Applies the MicroPython series, plus each module's own MicroPython patches, once, as one local commit. `--check` tests a change without applying it. |

docs/reference/index.md

@@ -1,15 +1,15 @@
 # Reference
 
 This repository has no Python package to document, so these pages are tables:
-what `build_mp.py` takes, the modules you can name, the boards and variants
+what [`build_mp.py`](https://github.com/PyDevices/micropython-pydevices/blob/main/build_mp.py) takes, the modules you can name, the boards and variants
 built, and the files that pin what a build uses.
 
 - [The build command](build-command.md): every option, environment variable and
   where output goes.
 - [Modules](modules.md): the short names `--modules` takes, and which build on
   CircuitPython.
 - [Boards and variants](boards.md): the command for each board, and every variant
-  in `variants/` and `boards/`.
+  in [`variants/`](https://github.com/PyDevices/micropython-pydevices/tree/main/variants) and [`boards/`](https://github.com/PyDevices/micropython-pydevices/tree/main/boards).
 - [Files and pins](files.md): `UPSTREAM`, the lock files, the patch series and
   the scripts.