Add MkDocs/RTD and finish MIP/TestPyPI cutover notes

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'scripts/mkdocs_gen_ref_pages.py'
+      - 'lib/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'scripts/mkdocs_gen_ref_pages.py'
+      - 'lib/**'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install MkDocs dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Build documentation
+        run: mkdocs build

.gitignore

@@ -24,3 +24,4 @@ VERSION
 tools/sourcey-api/node_modules/
 tools/sourcey-api/dist/
 site/
+.venv-docs/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: docs/requirements.txt

AGENTS.md

@@ -46,3 +46,10 @@ from the cmods workspace root when the usermod is linked into those interpreters
 
 Font C headers: `python3 scripts/sync_fonts.py` (source of truth is
 `lib/pygraphics/_font_8x*.py`).
+
+## Documentation
+
+- MkDocs under `docs/` → https://pygraphics.readthedocs.io (`.readthedocs.yaml`)
+- Sourcey native API under `tools/sourcey-api/` → Pages `/api/`
+- Local: `python3 -m venv .venv-docs && .venv-docs/bin/pip install -r docs/requirements.txt && .venv-docs/bin/mkdocs serve`
+

README.md

@@ -1,6 +1,6 @@
-# graphics
+# pygraphics
 
-Native and pure-Python **graphics** for MicroPython, CircuitPython, and CPython.
+Native and pure-Python **pygraphics** for MicroPython, CircuitPython, and CPython.
 Import as `pygraphics`.
 
 | Product | Pip / MIP | Role |
@@ -58,6 +58,7 @@ print(pygraphics.implementation())  # native_cmod or pygraphics_python
 
 ## Links
 
+- [Documentation](https://pygraphics.readthedocs.io)
 - [Source-linked API reference](https://pydevices.github.io/pygraphics/api/)
 - [Source](https://github.com/PyDevices/pygraphics)
 - [Issues](https://github.com/PyDevices/pygraphics/issues)
@@ -74,7 +75,7 @@ MIT (framebuf algorithms derived from MicroPython `extmod/modframebuf.c`, Damien
 ### Layout
 
 ```
-graphics/
+pygraphics/
   micropython.mk / micropython.cmake / circuitpython.mk / setup.py
   src/                     # C sources + headers (gfx_*.h, font_8x*.h, qstrs)
   lib/pygraphics/            # pure-Python package (import pygraphics)

docs/README.md

@@ -1,20 +1,14 @@
-# API reference site
+# Documentation
 
-This directory contains the reproducible Sourcey reference for the native
-`pygraphics` module. The generator reads the CPython binding tables and public C
-headers at the checked-out commit, then emits source-linked Markdown for the
-Python and native integration surfaces.
+Hand-authored MkDocs pages live in this directory and publish to
+[pygraphics.readthedocs.io](https://pygraphics.readthedocs.io).
 
 ```bash
-cd docs
-npm ci
-npm run check
+python3 -m venv .venv-docs
+.venv-docs/bin/pip install -r docs/requirements.txt
+.venv-docs/bin/mkdocs serve   # or: mkdocs build
 ```
 
-`npm run check` regenerates the reference, builds the static site into `dist/`,
-and verifies API coverage, immutable source links, project-scoped search URLs,
-canonical URLs, and integration with the existing Pages deployment. Generated
-HTML remains untracked build output.
-
-The existing Pages workflow preserves the project homepage and publishes the
-Sourcey build below `/pygraphics/api/` after a merge to `main`.
+The native (C) source-linked API is built separately with Sourcey under
+[`tools/sourcey-api/`](../tools/sourcey-api/) and deployed to
+[pydevices.github.io/pygraphics/api/](https://pydevices.github.io/pygraphics/api/).

docs/SUMMARY.md

@@ -0,0 +1,5 @@
+* [Home](index.md)
+* [Getting started](getting-started.md)
+* [Installation](installation.md)
+* [Publishing](publishing.md)
+* [API Reference](reference/)

docs/getting-started.md

@@ -0,0 +1,40 @@
+# Getting started
+
+## Setup
+
+Install from [MIP](installation.md) or [TestPyPI](installation.md):
+
+```python
+import mip
+mip.install("pygraphics", index="https://PyDevices.github.io/micropython-lib/mip/PyDevices")
+```
+
+Development clone — put `lib/` on `PYTHONPATH`, or `pip install -e .` for the
+native cmod.
+
+## Basic usage
+
+```python
+import pygraphics
+from pygraphics import FrameBuffer, RGB565, Area
+
+fb = FrameBuffer(bytearray(160 * 128 * 2), 160, 128, RGB565)
+fb.fill(0)
+area = fb.fill_rect(10, 10, 40, 40, 0xF800)
+assert isinstance(area, Area)
+print(pygraphics.implementation())  # native_cmod or pygraphics_python
+```
+
+## What you get
+
+- `Area` — rectangle geometry for dirty regions / clipping
+- `FrameBuffer` — framebuf-compatible surface; draw methods return `Area`
+- Format constants: `MONO_*`, `RGB565`, `GS*`, `RGB888`
+- `Draw`, `Font`, BMP565 / PBM / PGM helpers
+- `framebuf_backend()`, `capabilities()`, `implementation()`
+
+## Examples
+
+Drawing demos live in
+[pydisplay `src/examples/`](https://github.com/PyDevices/pydisplay/tree/main/src/examples)
+(`graphics_simpletest.py`, BMP565 samples, and others).

docs/index.md

@@ -0,0 +1,22 @@
+# pygraphics
+
+**pygraphics** is the cross-platform 2D drawing package for the PyDevices stack —
+`Area`, framebuf-compatible `FrameBuffer`, fonts, shapes, and image loaders for
+MicroPython, CircuitPython, and CPython.
+
+| Product | Channel | Role |
+|---------|---------|------|
+| **pygraphics-cmod** | TestPyPI | All-C extension (`implementation()` → `native_cmod`) |
+| **pygraphics** | TestPyPI + MIP | Pure-Python package (`pygraphics_python`) |
+
+Same public API either way. Prefer the cmod on desktop/Android when a matching
+wheel is available.
+
+## Links
+
+- [Getting started](getting-started.md)
+- [Installation](installation.md)
+- [API Reference](reference/pygraphics/index.md)
+- [Native source-linked API (Pages)](https://pydevices.github.io/pygraphics/api/)
+- [pydisplay documentation](https://pydisplay.readthedocs.io)
+- [GitHub](https://github.com/PyDevices/pygraphics)

docs/installation.md

@@ -0,0 +1,47 @@
+# Installation
+
+## MicroPython (MIP)
+
+```python
+import mip
+mip.install("pygraphics", index="https://PyDevices.github.io/micropython-lib/mip/PyDevices")
+```
+
+The package path on micropython-lib is `micropython/pygraphics/` (import name
+`pygraphics`). Older installs that used MIP name `graphics` should reinstall
+under the new name after the next publish.
+
+## CircuitPython / copy install
+
+Copy the `pygraphics/` package folder onto `sys.path` (from
+`lib/pygraphics/` in this repo, or from micropython-lib).
+
+## CPython — native (preferred when available)
+
+```bash
+pip install \
+  -i https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  pygraphics-cmod
+```
+
+## CPython — pure Python
+
+```bash
+pip install \
+  -i https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  pygraphics
+```
+
+## Name cutover
+
+| Role | Current | Retired (do not use) |
+|------|---------|----------------------|
+| Import | `pygraphics` | `graphics` |
+| Pure-Python pip | `pygraphics` | `pydisplay-graphics` |
+| Native pip | `pygraphics-cmod` | `graphics-cmod` |
+| MIP | `pygraphics` | `graphics` |
+
+TestPyPI may still list the old project names until they age out; install the
+**current** names above.

docs/PUBLISHING.md → docs/publishing.md

@@ -10,17 +10,17 @@ One annotated tag `vX.Y.Z` publishes **both** products at that version:
 ## Pipeline
 
 ```text
-graphics (commit on main)
+pygraphics (commit on main)
   ./scripts/publish_release_tag.sh --push   # next patch after highest v*
            │
            ├─► publish-testpypi.yml
            │     cibuildwheel → Linux + Windows + Android → pygraphics-cmod
            │
            └─► publish-micropython-lib.yml
-                 sync → micropython/graphics/
+                 sync → micropython/pygraphics/
                  hatch + twine → pygraphics
                  rebuild mip/PyDevices → gh-pages
-                 remove legacy micropython/pydisplay/graphics/
+                 remove legacy micropython/graphics/ and pydisplay/graphics/
 ```
 
 ## Version numbers
@@ -43,7 +43,7 @@ release is **`v0.0.25`** (not `v0.0.11`). Later tags continue from the highest
 | `TESTPYPI_API_TOKEN` | TestPyPI upload (cmod + pygraphics) |
 | `MICROPYTHON_LIB_DEPLOY_TOKEN` | PAT with `contents:write` on PyDevices/micropython-lib |
 
-Grant both secrets to the **graphics** repository (org secret repository access).
+Grant both secrets to the **pygraphics** repository (org secret repository access).
 
 ## Install
 
@@ -67,3 +67,10 @@ python3 -m venv .venv
 .venv/bin/pip install -e .
 .venv/bin/python tests/test_pygraphics.py
 ```
+
+## Documentation
+
+- **Read the Docs** (guides + pure-Python API): https://pygraphics.readthedocs.io  
+  Config: `.readthedocs.yaml` + `mkdocs.yml`. Import the GitHub repo once in the
+  RTD dashboard with slug `pygraphics` if the project is not live yet.
+- **GitHub Pages** (marketing + Sourcey native API): https://pydevices.github.io/pygraphics/

docs/requirements.txt

@@ -0,0 +1,7 @@
+mkdocs>=1.6
+mkdocs-material>=9.5
+mkdocstrings[python]>=0.26
+mkdocs-gen-files>=0.5
+mkdocs-literate-nav>=0.6
+mkdocs-section-index>=0.3
+mkdocs-jupyter>=0.25

docs/stylesheets/extra.css

@@ -0,0 +1,56 @@
+/*
+ * PyDevices brand colors for Material for MkDocs.
+ * Tokens mirror https://pydevices.github.io/assets/css/site.css
+ */
+
+:root > * {
+  --md-primary-fg-color: #f54e00;
+  --md-primary-fg-color--light: #ff7a3d;
+  --md-primary-fg-color--dark: #c33f00;
+  --md-primary-bg-color: #fff7f1;
+  --md-primary-bg-color--light: rgba(255, 247, 241, 0.7);
+
+  --md-accent-fg-color: #ff7a3d;
+  --md-accent-fg-color--transparent: rgba(245, 78, 0, 0.1);
+  --md-accent-bg-color: #1a0d05;
+  --md-accent-bg-color--light: rgba(26, 13, 5, 0.7);
+}
+
+[data-md-color-scheme="default"] {
+  --md-default-bg-color: #fbf9f5;
+  --md-default-bg-color--light: #f3eee6;
+  --md-default-bg-color--lighter: #f6f1e9;
+  --md-default-bg-color--lightest: #ffffff;
+  --md-default-fg-color: #201c16;
+  --md-default-fg-color--light: #5b5347;
+  --md-default-fg-color--lighter: #8a8172;
+  --md-default-fg-color--lightest: #c9bfae;
+  --md-typeset-a-color: #c33f00;
+  --md-code-bg-color: #f6f1e9;
+  --md-code-fg-color: #201c16;
+  --md-footer-bg-color: #f3eee6;
+  --md-footer-bg-color--dark: #201c16;
+  --md-footer-fg-color: #201c16;
+  --md-footer-fg-color--light: #5b5347;
+  --md-footer-fg-color--lighter: #8a8172;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-hue: 32;
+  --md-default-bg-color: #100e0b;
+  --md-default-bg-color--light: #17130f;
+  --md-default-bg-color--lighter: #1c1712;
+  --md-default-bg-color--lightest: #241e17;
+  --md-default-fg-color: #f3ecdf;
+  --md-default-fg-color--light: #c9bfae;
+  --md-default-fg-color--lighter: #8f8474;
+  --md-default-fg-color--lightest: #5b5347;
+  --md-typeset-a-color: #ff8a52;
+  --md-code-bg-color: #1c1712;
+  --md-code-fg-color: #f3ecdf;
+  --md-footer-bg-color: #17130f;
+  --md-footer-bg-color--dark: #100e0b;
+  --md-footer-fg-color: #f3ecdf;
+  --md-footer-fg-color--light: #c9bfae;
+  --md-footer-fg-color--lighter: #8f8474;
+}

mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: pygraphics
+site_url: https://pygraphics.readthedocs.io
+repo_url: https://github.com/PyDevices/pygraphics/
+edit_uri: edit/main/docs/
+copyright: "Copyright 2024, Brad Barnett"
+docs_dir: docs
+site_dir: site
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - content.code.copy
+
+extra_css:
+  - stylesheets/extra.css
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - scripts/mkdocs_gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [lib]
+          options:
+            show_source: false
+            show_root_heading: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            docstring_style: google
+            merge_init_into_class: true
+            filters:
+              - "!^_"