From a72952edffccb02b8e89a0d2894bee80c3b196f2 Mon Sep 17 00:00:00 2001 From: Brad Barnett <127794626+bdbarnett@users.noreply.github.com> Date: Tue, 27 Oct 2026 09:16:04 -0500 Subject: [PATCH] Docs: link the repo paths the prose names --- CONTRIBUTING.md | 16 ++++++++-------- docs/how-it-works/generator-architecture.md | 14 +++++++------- docs/reference/fonts.md | 2 +- docs/reference/index.md | 2 +- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbb9cdb..2149377 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,7 +54,7 @@ consumer repositories don't need this clone beside them: each one's Make a small change in `binding/` or the LVGL submodule, regenerate the target you need, sync the generated files into the consumer repository, then rebuild that repository's firmware or extension. For a change to the Python helpers -only, start with `python/fs_driver.py` and the consumer sync script. If you +only, start with [`python/fs_driver.py`](python/fs_driver.py) and the consumer sync script. If you changed the C API surface or the LVGL headers, regenerate and rebuild a consumer before trusting the result. @@ -93,11 +93,11 @@ The unified command preprocesses LVGL once and writes the selected target's C source, the target-neutral `api.json`, the shared `lvgl.pp`, the CircuitPython generated header and the shared `lvgl.pyi`. The API model is hashed and includes visibility and target availability; deliberate exceptions live in -`binding/api_policy.json`. Preprocessing removes compiler line markers, so the +[`binding/api_policy.json`](binding/api_policy.json). Preprocessing removes compiler line markers, so the inputs are reproducible across checkout paths. `--check` generates into a temporary directory and never changes the working tree. -The stub comes only from the canonical `generated/api.json`. Use `--pyi-only` +The stub comes only from the canonical [`generated/api.json`](generated/api.json). Use `--pyi-only` when you change typing emission, so the C bindings, the model and the preprocessed input aren't regenerated. The public names are the one upstream-compatible profile; there is no alternate naming mode. @@ -115,7 +115,7 @@ TMPDIR=/tmp/lvgl-bindings-pytest .venv/bin/python -m pytest -q -s tests ./scripts/release_dry_run.sh # the complete non-mutating release gate ``` -`scratch/upstream_baseline/run.sh` verifies that the pinned upstream generator +[`scratch/upstream_baseline/run.sh`](scratch/upstream_baseline/run.sh) verifies that the pinned upstream generator still reproduces the baseline, without keeping its source or full outputs in this repository. All of its output is created in a temporary directory and removed on exit. Set `LVGL_BINDINGS_UPSTREAM_REPO` to reuse a checkout at the @@ -123,16 +123,16 @@ pinned commit instead of cloning one. `linux-integration.yml` builds the MicroPython and CircuitPython unix ports with lvgl-micropython and lvgl-circuitpython pinned at the commit under test, -and runs `tools/test_lvgl_smoke.py` on each. CPython rebuilds its extension and +and runs [`tools/test_lvgl_smoke.py`](tools/test_lvgl_smoke.py) on each. CPython rebuilds its extension and wheel from the synced source. ## The consumers | Repository | What it takes from here | |---|---| -| [lvgl-micropython](https://github.com/PyDevices/lvgl-micropython) | `generated/lvgl_micropython.c`, `lvgl/`, `lv_conf.h`, `python/fs_driver.py` into `lib/` | -| [lvgl-circuitpython](https://github.com/PyDevices/lvgl-circuitpython) | `generated/lvgl_circuitpython.c` and `.h`, `lvgl/`, `lv_conf.h`, `python/fs_driver.py` into `lib/` | -| [lvgl-python](https://github.com/PyDevices/lvgl-python) | `generated/lvgl_python.c`, `generated/lvgl.pyi`, `lvgl/`, `lv_conf.h` and the helpers; the one that publishes the wheel | +| [lvgl-micropython](https://github.com/PyDevices/lvgl-micropython) | [`generated/lvgl_micropython.c`](generated/lvgl_micropython.c), `lvgl/`, `lv_conf.h`, `python/fs_driver.py` into `lib/` | +| [lvgl-circuitpython](https://github.com/PyDevices/lvgl-circuitpython) | [`generated/lvgl_circuitpython.c`](generated/lvgl_circuitpython.c) and `.h`, `lvgl/`, `lv_conf.h`, `python/fs_driver.py` into `lib/` | +| [lvgl-python](https://github.com/PyDevices/lvgl-python) | [`generated/lvgl_python.c`](generated/lvgl_python.c), [`generated/lvgl.pyi`](generated/lvgl.pyi), `lvgl/`, `lv_conf.h` and the helpers; the one that publishes the wheel | Each consumer records the resolved source SHA in `LVGL_BINDINGS_COMMIT`. Its sync script rejects branch names, so a downstream build can't silently move to diff --git a/docs/how-it-works/generator-architecture.md b/docs/how-it-works/generator-architecture.md index 6112883..cd58e92 100644 --- a/docs/how-it-works/generator-architecture.md +++ b/docs/how-it-works/generator-architecture.md @@ -18,13 +18,13 @@ LVGL headers + lv_conf.h - `requirements.txt` pins `pycparser==3.0`; `fake_libc_include/` is vendored from the matching parser release. Parser or fake-libc changes require full regeneration and all-target validation. -- `binding/ir.py` is the target-neutral declaration representation. -- `binding/api_model.py` defines the public Python model. The generated, - schema-versioned `generated/api.json` includes a deterministic content hash. -- `binding/api_policy.json` is the reviewed exception manifest. Unsupported +- [`binding/ir.py`](../../binding/ir.py) is the target-neutral declaration representation. +- [`binding/api_model.py`](../../binding/api_model.py) defines the public Python model. The generated, + schema-versioned [`generated/api.json`](../../generated/api.json) includes a deterministic content hash. +- [`binding/api_policy.json`](../../binding/api_policy.json) is the reviewed exception manifest. Unsupported public declarations are fatal unless an exact policy entry records the declaration, affected targets, reason, and test coverage. -- `binding/emit_pyi_canonical.py` emits `generated/lvgl.pyi` only from +- [`binding/emit_pyi_canonical.py`](../../binding/emit_pyi_canonical.py) emits [`generated/lvgl.pyi`](../../generated/lvgl.pyi) only from `generated/api.json`. Generated C is never edited by hand. The committed outputs are @@ -95,8 +95,8 @@ coordinator, in PyDevices/pydevices `lib/` — reads calls from inside an LVGL callback. From inside this translation unit the counter looks unused (nothing here reads it back), but its only reader is Python code outside the generated C; do not remove it on that "dead code" -appearance. `tests/test_nesting_export.py` guards this by reading the names +appearance. [`tests/test_nesting_export.py`](../../tests/test_nesting_export.py) guards this by reading the names the freshly generated MicroPython/CircuitPython C exports; pydevices' `tests/test_lvgl_display_driver.py` holds the reader's side. -How to run the generator and its checks is in [CONTRIBUTING](https://github.com/PyDevices/lvgl-bindings/blob/main/CONTRIBUTING.md). The consumer builds are part of integration validation: the `linux-integration.yml` workflow builds the MicroPython and CircuitPython unix ports with lvgl-micropython and lvgl-circuitpython pinned at the commit under test, and runs `tools/test_lvgl_smoke.py` on each. CPython rebuilds its extension and wheel from the synced source. +How to run the generator and its checks is in [CONTRIBUTING](https://github.com/PyDevices/lvgl-bindings/blob/main/CONTRIBUTING.md). The consumer builds are part of integration validation: the `linux-integration.yml` workflow builds the MicroPython and CircuitPython unix ports with lvgl-micropython and lvgl-circuitpython pinned at the commit under test, and runs [`tools/test_lvgl_smoke.py`](../../tools/test_lvgl_smoke.py) on each. CPython rebuilds its extension and wheel from the synced source. diff --git a/docs/reference/fonts.md b/docs/reference/fonts.md index babc824..0746bda 100644 --- a/docs/reference/fonts.md +++ b/docs/reference/fonts.md @@ -65,7 +65,7 @@ image sources like `lv.image.set_src("S:logo.png")` work through it too. ### Where fs_driver comes from -The canonical copy is `python/fs_driver.py` in lvgl-bindings. Each package +The canonical copy is [`python/fs_driver.py`](../../python/fs_driver.py) in lvgl-bindings. Each package ships a synced copy: frozen into lvgl-micropython and lvgl-circuitpython builds, `py_modules` in the lvgl-python wheel — so `import fs_driver` just works. For a stock MicroPython diff --git a/docs/reference/index.md b/docs/reference/index.md index 50fae87..8d2a855 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -6,7 +6,7 @@ the reference for what each widget, style and function does. This page says how the C names map to Python, and what the binding leaves out. The exact names your build has are in the type stub, `lvgl.pyi`. Wheels install -it beside the `lvgl` extension module, and `generated/lvgl.pyi` in +it beside the `lvgl` extension module, and [`generated/lvgl.pyi`](../../generated/lvgl.pyi) in [lvgl-bindings](https://github.com/PyDevices/lvgl-bindings/blob/main/generated/lvgl.pyi) is the shared copy. If your checker doesn't pick it up, set `python.analysis.stubPath` (Pylance) or `stubPath` (pyright) to a directory