Docs: Sphinx on the shared documentation package

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+# The docs site as Read the Docs builds it: from the repository root, with
+# docs/requirements.txt, and every warning a failure.
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'lib/**'
+      - '.readthedocs.yaml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'lib/**'
+      - '.readthedocs.yaml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+      - name: Install docs requirements
+        run: pip install -r docs/requirements.txt
+      - name: Build docs
+        run: sphinx-build -W --keep-going -b html docs _site

.gitignore

@@ -27,5 +27,6 @@ tools/sourcey-api/node_modules/
 tools/sourcey-api/dist/
 # Generated API reference: regenerate with tools/sourcey-api/scripts/generate_reference.py
 tools/sourcey-api/generated/
-site/
+docs/_build/
+docs/reference/
 .venv-docs/

.readthedocs.yaml

@@ -5,8 +5,9 @@ build:
   tools:
     python: "3.13"
 
-mkdocs:
-  configuration: mkdocs.yml
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
 
 python:
   install:

AGENTS.md

@@ -59,9 +59,9 @@ Font C headers: `python3 scripts/sync_fonts.py` (source of truth is
 
 ## Documentation
 
-- MkDocs under `docs/` → https://pygraphics.readthedocs.io (`.readthedocs.yaml`)
+- Sphinx under `docs/` (MyST Markdown, `docs/conf.py`) → https://pygraphics.readthedocs.io (`.readthedocs.yaml`)
 - Sourcey native-C API generator under `tools/sourcey-api/`; output is gitignored and unpublished (regenerate with `scripts/generate_reference.py`)
-- Local: `python3 -m venv .venv-docs && .venv-docs/bin/pip install -r docs/requirements.txt && .venv-docs/bin/mkdocs serve`
+- Local: `python3 -m venv .venv-docs && .venv-docs/bin/pip install -r docs/requirements.txt && .venv-docs/bin/sphinx-build -W --keep-going -b html docs docs/_build/html`
 - Use practical examples from `pydevices-examples` and emphasize off-screen
   rendering, dirty-rectangle updates, hit testing, sprite blits, gradients, and
   text drawing.

docs/README.md

@@ -1,15 +1,15 @@
 # Documentation
 
-Hand-authored MkDocs pages live in this directory and publish to
+Hand-authored Markdown pages (built by Sphinx; `conf.py` is here) live in this directory and publish to
 [pygraphics.readthedocs.io](https://pygraphics.readthedocs.io).
 
 ```bash
 python3 -m venv .venv-docs
 .venv-docs/bin/pip install -r docs/requirements.txt
-.venv-docs/bin/mkdocs serve   # or: mkdocs build
+.venv-docs/bin/sphinx-build -W --keep-going -b html docs docs/_build/html
 ```
 
-A source-linked reference for the **native C bindings** — which mkdocstrings
+A source-linked reference for the **native C bindings** — which autodoc
 cannot reach, since it reads Python docstrings — can be generated on demand with
 Sourcey under [`tools/sourcey-api/`](../tools/sourcey-api/):
 

docs/api-overview.md

@@ -1,3 +1,5 @@
+# API overview
+
 `pygraphics` extends `framebuf` with extra drawing helpers (rounded rectangles, gradients, polygons) and returns **Area** bounding boxes for partial updates.
 
 See the [installation guide](installation.md) for MIP and TestPyPI options.

docs/building-wheels.md

@@ -47,7 +47,7 @@ pydevices_pygraphics-<version>-cp314-cp314-pyemscripten_2026_0_wasm32.whl
 ## Documentation
 
 - **Read the Docs** (guides + pure-Python API): https://pygraphics.readthedocs.io  
-  Config: `.readthedocs.yaml` + `mkdocs.yml`. Connected via the org
+  Config: `.readthedocs.yaml` + `docs/conf.py`. Connected via the org
   [Read the Docs Community GitHub App](https://github.com/organizations/PyDevices/settings/installations)
   (no per-repo webhook). See pydevices-examples
   [Building docs](https://github.com/PyDevices/.github/blob/main/docs/building-docs.md) for

docs/conf.py

@@ -0,0 +1,17 @@
+"""Sphinx configuration for the pygraphics documentation.
+
+Everything shared by the PyDevices documentation projects (theme, top bar,
+Markdown and docstring setup, the reference map) comes from pydevices-docs.
+"""
+
+from pydevices_docs import configure
+
+globals().update(configure(
+    "pygraphics", __file__,
+    repo="PyDevices/pygraphics", edit_path="docs",
+    source_dirs=["../lib"], api_packages=["pygraphics"],
+    # The public names live in private modules and are re-exported by
+    # pygraphics/__init__.py's __all__, which is what the reference documents.
+    use_module_all=True,
+    version_file="../VERSION",
+))

docs/getting-started.md

@@ -2,45 +2,54 @@
 
 ## Setup
 
-=== "MicroPython (MIP)"
+::::{tab-set}
 
-    ```python
-    import mip
-    mip.install("pygraphics", index="https://PyDevices.github.io/mip")
-    ```
+:::{tab-item} MicroPython (MIP)
 
-=== "CPython (TestPyPI)"
+```python
+import mip
+mip.install("pygraphics", index="https://PyDevices.github.io/mip")
+```
+:::
+
+:::{tab-item} CPython (TestPyPI)
+
+```bash
+pip install -i https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ pydevices-pygraphics
+```
+:::
 
-    ```bash
-    pip install -i https://test.pypi.org/simple/ \
-      --extra-index-url https://pypi.org/simple/ pydevices-pygraphics
-    ```
+:::{tab-item} CircuitPython
 
-=== "CircuitPython"
+Copy `lib/pygraphics/` to your board's `CIRCUITPY/lib/` directory.
+:::
 
-    Copy `lib/pygraphics/` to your board's `CIRCUITPY/lib/` directory.
+:::{tab-item} PyScript / Pyodide
 
-=== "PyScript / Pyodide"
+```python
+import micropip
+await micropip.install(
+    "pydevices-pygraphics", index_urls="https://test.pypi.org/simple/"
+)
 
-    ```python
-    import micropip
-    await micropip.install(
-        "pydevices-pygraphics", index_urls="https://test.pypi.org/simple/"
-    )
+import pygraphics
+```
 
-    import pygraphics
-    ```
+The wheel is named `pydevices-pygraphics`; the module you import is
+`pygraphics`. On MicroPython the MIP package name is `pygraphics`
+(`mip.install("pygraphics", index="https://PyDevices.github.io/mip")`).
+:::
 
-    The wheel is named `pydevices-pygraphics`; the module you import is
-    `pygraphics`. On MicroPython the MIP package name is `pygraphics`
-    (`mip.install("pygraphics", index="https://PyDevices.github.io/mip")`).
+::::
 
 ---
 
 ## 💻 Live Interactive Drawing Canvas
 
 Experiment with 2D shapes, colors, and font rendering live in your browser:
 
+````{raw} html
 <div class="pydevices-live-demo">
   <div class="demo-editor-pane">
     <textarea class="code-editor">
@@ -75,6 +84,7 @@ print(f"Shapes drawn! Dirty bounds: {area1 + area2}")
     <canvas id="canvas_pygraphics_getting_started" width="240" height="200" tabindex="0"></canvas>
   </div>
 </div>
+````
 
 ---
 

docs/graphics-guide.md

@@ -2,12 +2,14 @@
 
 Cross-platform 2D drawing: framebuf-compatible buffers, shape primitives that return **Area** bounds, fonts, and image loaders. One import works on MicroPython, CircuitPython, and CPython.
 
-!!! note "Where the pieces live"
-    `pygraphics` is maintained here. Install it from the
-    [PyDevices MIP index](installation.md) (`mip.install("pygraphics", index=…)`)
-    or from TestPyPI as `pydevices-pygraphics`. The `utils` modules referenced
-    below (`displaybuf`, `tft_text`, …) ship with
-    [pydevices-examples](https://github.com/PyDevices/pydevices-examples).
+:::{admonition} Where the pieces live
+:class: note
+`pygraphics` is maintained here. Install it from the
+[PyDevices MIP index](installation.md) (`mip.install("pygraphics", index=…)`)
+or from TestPyPI as `pydevices-pygraphics`. The `utils` modules referenced
+below (`displaybuf`, `tft_text`, …) ship with
+[pydevices-examples](https://github.com/PyDevices/pydevices-examples).
+:::
 
 ## Quick start
 
@@ -29,7 +31,7 @@ inspect or branch on.
 
 ## Drawing Pipeline Architecture
 
-```mermaid
+```{mermaid}
 flowchart TD
     subgraph Primitives ["Drawing Operations"]
         P1["fill_rect(x, y, w, h)"]