Test documentation examples in CI

.github/workflows/test-doc-code.yaml

@@ -0,0 +1,49 @@
+name: Run Doc Examples
+
+on:
+  # trigger on pull requests
+  pull_request:
+
+  # trigger on all commits to main
+  push:
+    branches:
+      - 'main'
+
+  # trigger on request
+  workflow_dispatch:
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest]
+        python: ['3.12']
+    steps:
+    - name: Checkout
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29  # v4.2.1
+    - name: Set up Python ${{ matrix.python }}
+      uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
+      with:
+        python-version: ${{ matrix.python }}
+    - name: Set up Python environment
+      uses: glotzerlab/workflows/setup-uv@3573ddaebf3290e00bfb150b82a46412192a61d3
+      with:
+        # only-binary: ":none:"
+        lockfile: ".github/requirements${{ matrix.python }}.txt"
+    - name: Install package
+      run: |
+        python --version
+        uv pip install . --no-build-isolation --no-deps --system -v
+    - name: Extract Documentation Code
+      run: |
+        awk '
+            /```python/ {in_block=1; file="README_code_block" ++count ".py"; next}
+            /```/ {in_block=0; next}
+            in_block {print > file}
+            ' README.md
+    - name: Test Documentation Code
+      run: for f in README_code_block*.py; do python3 "$f"; done && echo OK

README.md

@@ -78,6 +78,8 @@ for view, view_type in zip([iso, dim, tri], ["iso", "dim", "tri"]):
 In addition to convenience methods, `svg3d` allows full control over the viewport, scene geometry, image style, and shaders. Methods are based on OpenGL standards and nomenclature where possible, and images can be created from any set of vertices and faces - even from ragged arrays! Simply pass an array of vertices and a list of arrays (one for vertex indices of each face, as below) to `svg3d.Mesh.from_vertices_and_faces` to render whatever geometry you like. Custom shader models can be implemented as a callable that takes a face index and a `svg3d.Mesh` object to shade.
 
 ```python
+import numpy as np
+
 import svg3d
 
 # Define the vertices and faces of a cube