Add markdown-code-runner workflow for auto-updating docs

- Add docs/run_markdown_code_runner.py script to process all docs
- Add GitHub workflow to run on push/PR and auto-commit changes

Author: basnijholt

.github/workflows/markdown-code-runner.yml

@@ -0,0 +1,53 @@
+name: markdown-code-runner
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  markdown-code-runner:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Run markdown-code-runner
+        env:
+          PYTHONPATH: ${{ github.workspace }}/custom_components:${{ github.workspace }}
+        run: |
+          uv sync --group docs
+          uv run python docs/run_markdown_code_runner.py
+
+      - name: Commit updated docs
+        id: commit
+        run: |
+          git add -A
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          if git diff --quiet && git diff --staged --quiet; then
+            echo "No changes in docs, skipping commit."
+            echo "commit_status=skipped" >> $GITHUB_ENV
+          else
+            git commit -m "Update auto-generated docs"
+            echo "commit_status=committed" >> $GITHUB_ENV
+          fi
+
+      - name: Push changes
+        if: env.commit_status == 'committed'
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.head_ref }}

docs/run_markdown_code_runner.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+# ruff: noqa: T201, S603, S607
+"""Update all markdown files that use markdown-code-runner for auto-generation.
+
+Run from repo root: uv run python docs/run_markdown_code_runner.py
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]:
+    """Find all markdown files containing markdown-code-runner markers."""
+    files_with_code = []
+    for md_file in docs_dir.rglob("*.md"):
+        content = md_file.read_text()
+        if "<!-- CODE:START -->" in content:
+            files_with_code.append(md_file)
+    return sorted(files_with_code)
+
+
+def run_markdown_code_runner(files: list[Path], repo_root: Path) -> bool:
+    """Run markdown-code-runner on all files. Returns True if all succeeded."""
+    if not files:
+        print("No files with CODE:START markers found.")
+        return True
+
+    print(f"Found {len(files)} file(s) with auto-generated content:")
+    for f in files:
+        print(f"  - {f.relative_to(repo_root)}")
+    print()
+
+    all_success = True
+    for file in files:
+        rel_path = file.relative_to(repo_root)
+        print(f"Updating {rel_path}...", end=" ", flush=True)
+        result = subprocess.run(
+            ["markdown-code-runner", str(file)],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            print("✓")
+        else:
+            print("✗")
+            print(f"  Error: {result.stderr}")
+            all_success = False
+
+    return all_success
+
+
+def main() -> int:
+    """Main entry point."""
+    repo_root = Path(__file__).parent.parent
+
+    # Also check README.md at repo root
+    files = find_markdown_files_with_code_blocks(repo_root / "docs")
+    readme = repo_root / "README.md"
+    if readme.exists() and "<!-- CODE:START -->" in readme.read_text():
+        files.append(readme)
+
+    success = run_markdown_code_runner(files, repo_root)
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())