Add tests for the code blocks in Markdown files (courtesy of @tlambert03)

.github/workflows/test_docs.yml

@@ -0,0 +1,42 @@
+name: Test docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test_release:
+    name: Test docs on latest release
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+        python:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/requirements-test.txt
+
+      - name: Test docs
+        run: |
+          python -m pytest -k test_tutorials --tb=short -s --color=yes --maxfail=5 --log-cli-level=0

.gitignore

@@ -1,2 +1,11 @@
 site/
 venv/
+.idea/
+
+# files generated by tests
+__pycache__/
+*.tif
+*.tiff
+*.zarr/
+sample_props.json
+sample_trig.json

tests/README.md

@@ -0,0 +1,16 @@
+# Testing the Documentation
+
+To test the documentation, you will need to have several packages installed in your Python environment.
+You can install them with the following command:
+
+```bash
+python -m pip install -r requirements-test.txt
+```
+
+(You can find the `requirements-test.txt` file in the folder containing this README file.)
+
+Then execute the tests with the following command:
+
+```bash
+python -m pytest
+```

tests/requirements-test.txt

@@ -0,0 +1,7 @@
+acquire-imaging
+napari[all]
+numpy
+ome-zarr
+pytest
+tifffile
+zarr

tests/test_tutorials.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+import re
+import logging
+import pytest
+
+
+logging.getLogger("acquire").setLevel(logging.CRITICAL)
+
+code_block_re = re.compile(r"( *)```python\n(.*?)```", re.DOTALL)
+skip = {
+    "setup.md",  # has invalid syntax
+    "trigger.md",  # has some non-existant paths
+}
+
+
+def tutorials():
+    docs_path = Path(__file__).parent.parent / "docs"
+
+    tuts = []
+    if (get_started := docs_path / "get_started.md").exists():
+        tuts.append(get_started)
+    tuts.extend([fn for fn in docs_path.glob("tutorials/*.md") if fn.name not in skip])
+    tuts.sort()
+
+    return tuts
+
+
+@pytest.mark.parametrize("tutorial", tutorials(), ids=lambda x: x.name)
+def test_tutorials(tutorial: Path):
+    for code_block in code_block_re.finditer(tutorial.read_text()):
+        whitespace = code_block.group(1)
+        if whitespace:
+            code_block = "\n".join(line[len(whitespace):] for line in code_block.group(2).split("\n"))
+        else:
+            code_block = code_block.group(2)
+        exec(code_block)