diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 562ebc7..5bba64c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to pygraphics pygraphics is two implementations of one API: C under `src/` and pure Python -under `lib/pygraphics/`. A change to one needs the same change in the other, +under [`lib/pygraphics/`](lib/pygraphics/). A change to one needs the same change in the other, and the tests run against both. A focused test, or a docs example that shows an existing call, is a good first contribution. @@ -15,7 +15,7 @@ an existing call, is a good first contribution. | `setup.py`, `pyproject.toml` | the CPython wheel | | `tests/` | one suite for both implementations; [tests/README.md](tests/README.md) explains the switch | | `tools/` | comparison tools and `benchmark.py` | -| `scripts/sync_fonts.py` | writes the C font headers from the Python font files | +| [`scripts/sync_fonts.py`](scripts/sync_fonts.py) | writes the C font headers from the Python font files | | `docs/` | the documentation site | ## Run the tests @@ -37,7 +37,7 @@ PYGRAPHICS_TEST_NATIVE=1 .venv/bin/python -m unittest discover -s tests These are the two runs CI makes on every change. `PYTHONPATH=lib` alone does not select the pure package once you've built in place, because the repository root comes before `PYTHONPATH` on `sys.path` and the compiled -module there wins. `tests/_env.py` handles that for the suite; from a shell, +module there wins. [`tests/_env.py`](tests/_env.py) handles that for the suite; from a shell, run from another directory. ## Compare the two implementations @@ -140,7 +140,7 @@ python3 -m venv .venv-docs The API reference under `docs/reference/` is generated during the build and isn't tracked. Sphinx reads Python docstrings, so it can't see the C module; -`tools/sourcey-api/` generates a reference for the C bindings on demand, and +[`tools/sourcey-api/`](tools/sourcey-api/) generates a reference for the C bindings on demand, and its README says how. ## Releases diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 13ca419..9372395 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -26,7 +26,7 @@ mip.install("pygraphics", index="https://PyDevices.github.io/mip") ## On a CircuitPython-compatible board -Copy the `lib/pygraphics/` folder from this repository to the board's +Copy the [`lib/pygraphics/`](https://github.com/PyDevices/pygraphics/tree/main/lib/pygraphics) folder from this repository to the board's `CIRCUITPY/lib/` folder. ## In the browser (Pyodide) diff --git a/docs/how-it-works/benchmarks.md b/docs/how-it-works/benchmarks.md index fdac57c..968e3e1 100644 --- a/docs/how-it-works/benchmarks.md +++ b/docs/how-it-works/benchmarks.md @@ -24,7 +24,7 @@ The pure package fills `RGB565` rectangles with numpy when it can import it ## Run it yourself -`tools/benchmark.py` is the script behind the table. It prints which package +[`tools/benchmark.py`](../../tools/benchmark.py) is the script behind the table. It prints which package it imported, then one line per call. ```bash diff --git a/docs/how-it-works/index.md b/docs/how-it-works/index.md index 36d26c4..073c975 100644 --- a/docs/how-it-works/index.md +++ b/docs/how-it-works/index.md @@ -27,7 +27,7 @@ The compiled package is C. It's what the `pydevices-pygraphics` wheels contain, and it can be built into MicroPython or CircuitPython firmware. `pygraphics.implementation()` returns `native_cmod`. -The pure-Python package is the `lib/pygraphics/` folder, the one mip +The pure-Python package is the [`lib/pygraphics/`](https://github.com/PyDevices/pygraphics/tree/main/lib/pygraphics) folder, the one mip installs. It runs on any Python with no compiler, and returns `pygraphics_python`. It carries `pygraphics.framebuf`, a Python copy of MicroPython's `framebuf`, so it runs the same on CPython and CircuitPython, @@ -43,7 +43,7 @@ that only the pure package has are listed under A `pygraphics.FrameBuffer` takes the same arguments as `framebuf.FrameBuffer`, uses the same format numbers, and draws the same pixels for the same calls. -A tool in the repository, `tools/compare_framebuf_mp.py`, checks this against +A tool in the repository, [`tools/compare_framebuf_mp.py`](../../tools/compare_framebuf_mp.py), checks this against MicroPython's own `framebuf`. Two things differ on purpose: drawing methods return an `Area` instead of `None`, and [text](../guides/draw-text.md#framebufs-text-looks-different) uses the romfont faces. diff --git a/docs/index.md b/docs/index.md index 94feb86..f6c0035 100644 --- a/docs/index.md +++ b/docs/index.md @@ -48,7 +48,8 @@ print("Drawn with", pygraphics.implementation()) [Install it](get-started/install.md), then draw [your first picture](get-started/first-program.md). The [guides](guides/draw-shapes.md) take one task each, the -[reference](reference/index) lists every name, and +[reference](https://pygraphics.readthedocs.io/en/latest/reference/index.html) +lists every name, and [How it works](how-it-works/index.md) explains the design. ```{toctree} diff --git a/docs/platforms.md b/docs/platforms.md index 6f988f2..76a03d4 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -10,7 +10,7 @@ | Pyodide, CPython 3.13 and 3.14 | compiled wheel (`pyemscripten_2025_0` and `pyemscripten_2026_0`) | the wheel builds; micropip picks the one for your Pyodide | | MicroPython, any port | pure-Python, from mip | the compiled module's tests and the comparison against `framebuf` run on the unix port on every change | | CircuitPython | pure-Python, copied to `CIRCUITPY/lib/` | not tested automatically | -| macOS, Linux on ARM | pure-Python | no compiled wheel: copy `lib/pygraphics/` onto your path | +| macOS, Linux on ARM | pure-Python | no compiled wheel: copy [`lib/pygraphics/`](https://github.com/PyDevices/pygraphics/tree/main/lib/pygraphics) onto your path | The compiled module can also be built into MicroPython or CircuitPython firmware; [CONTRIBUTING.md](https://github.com/PyDevices/pygraphics/blob/main/CONTRIBUTING.md#build-it-into-micropython)