ci: GitHub Pages docs and firmware/provisioner CI

.github/workflows/firmware-ci.yml

@@ -0,0 +1,55 @@
+name: Firmware CI
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "firmware/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "firmware/**"
+  workflow_dispatch:
+
+jobs:
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install clang-format
+        run: sudo apt-get update && sudo apt-get install -y clang-format
+
+      - name: Check formatting
+        run: |
+          find firmware/src firmware/include \
+            \( -name "*.cpp" -o -name "*.hpp" \) | \
+          xargs clang-format --dry-run --Werror
+
+  build:
+    name: Build
+    needs: format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio-${{ hashFiles('firmware/platformio.ini') }}
+
+      - name: Install PlatformIO
+        run: python -m pip install --upgrade pip && pip install -U platformio
+
+      - name: Build firmware
+        working-directory: firmware
+        run: pio run

.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+# Builds the firmware API documentation with Doxygen and publishes it to
+# GitHub Pages. Pages is configured with build_type "workflow", so this
+# workflow is the deployment source.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "firmware/src/**"
+      - "firmware/include/**"
+      - "firmware/Doxyfile"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+
+      - name: Generate API docs
+        working-directory: firmware
+        run: doxygen Doxyfile
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: firmware/build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/provisioner-ci.yml

@@ -0,0 +1,52 @@
+name: Provisioner CI
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "provisioner/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "provisioner/**"
+  workflow_dispatch:
+
+jobs:
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          working-directory: provisioner
+
+      - name: Install dependencies
+        run: uv sync
+        working-directory: provisioner
+
+      - name: Check formatting
+        run: uv run ruff format --check src/
+        working-directory: provisioner
+
+  typecheck:
+    name: Typecheck
+    needs: format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          working-directory: provisioner
+
+      - name: Install dependencies
+        run: uv sync
+        working-directory: provisioner
+
+      - name: Run mypy
+        run: uv run mypy src/
+        working-directory: provisioner

firmware/Doxyfile

@@ -0,0 +1,26 @@
+# Doxygen configuration for the bugbite firmware.
+# Only non-default options are set; Doxygen fills in the rest.
+# Generate locally with `make docs`; CI publishes the HTML to GitHub Pages.
+
+PROJECT_NAME           = "bugbite firmware"
+PROJECT_BRIEF          = "ESP32-C3-SuperMini smart relay firmware"
+
+OUTPUT_DIRECTORY       = build
+HTML_OUTPUT            = html
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+
+INPUT                  = src include
+RECURSIVE              = YES
+FILE_PATTERNS          = *.hpp *.cpp
+
+# Document every entity, including those without comments, and show the
+# namespace/class structure used across the modules.
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+JAVADOC_AUTOBRIEF      = YES
+
+# Class/collaboration diagrams (graphviz is installed in CI).
+HAVE_DOT               = YES
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = NO

firmware/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help build upload monitor flash clean menuconfig fmt
+.PHONY: help build upload monitor flash clean menuconfig fmt docs
 
 help: ## Show available commands
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage: make \033[36m<command>\033[0m\n\nCommands:\n"} \
@@ -28,3 +28,6 @@ menuconfig: ## Open the ESP-IDF SDK configuration menu
 
 fmt: ## Format all C++ source files with clang-format
 	@find src include -name "*.cpp" -o -name "*.hpp" 2>/dev/null | xargs clang-format -i
+
+docs: ## Generate the API documentation with Doxygen (build/html)
+	doxygen Doxyfile