diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..bf70e27 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 341f756..45ab446 100644 --- a/.gitignore +++ b/.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/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4b81448..6a17e5f 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/AGENTS.md b/AGENTS.md index c5643e3..93154cb 100644 --- a/AGENTS.md +++ b/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. diff --git a/docs/README.md b/docs/README.md index 725cf80..946588c 100644 --- a/docs/README.md +++ b/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/): diff --git a/docs/api-overview.md b/docs/api-overview.md index fcd01e8..7427ad6 100644 --- a/docs/api-overview.md +++ b/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. diff --git a/docs/assets/pyscript/pydevices-runner.js b/docs/assets/pyscript/pydevices-runner.js deleted file mode 100644 index 70fbcf2..0000000 --- a/docs/assets/pyscript/pydevices-runner.js +++ /dev/null @@ -1,4 +0,0 @@ -/** Load the first-party direct MicroPython documentation host. */ -import("https://PyDevices.github.io/assets/chrome/docs-runtime.js").catch((error) => { - console.error("Unable to load the PyDevices documentation runtime:", error); -}); diff --git a/docs/building-wheels.md b/docs/building-wheels.md index 492639a..31def40 100644 --- a/docs/building-wheels.md +++ b/docs/building-wheels.md @@ -47,7 +47,7 @@ pydevices_pygraphics--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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..eed7eeb --- /dev/null +++ b/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", +)) diff --git a/docs/getting-started.md b/docs/getting-started.md index 791fad7..a540c41 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,38 +2,46 @@ ## 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")`). +:::: --- @@ -41,6 +49,7 @@ Experiment with 2D shapes, colors, and font rendering live in your browser: +````{raw} html