From 372b4ae90668ff1c07e3a44a8d6c1f24aea75fd6 Mon Sep 17 00:00:00 2001 From: JMTamayo Date: Mon, 15 Jun 2026 17:24:53 -0500 Subject: [PATCH 1/2] ci: publish firmware Doxygen API docs to GitHub Pages Add a Doxygen config that renders the firmware's documented C++ API to HTML, a make docs target to generate it locally, and a GitHub Actions workflow that builds the docs and deploys them to GitHub Pages (Pages is configured with the workflow build type). --- .github/workflows/pages.yml | 51 +++++++++++++++++++++++++++++++++++++ firmware/Doxyfile | 26 +++++++++++++++++++ firmware/Makefile | 5 +++- 3 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/pages.yml create mode 100644 firmware/Doxyfile diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..b634137 --- /dev/null +++ b/.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 diff --git a/firmware/Doxyfile b/firmware/Doxyfile new file mode 100644 index 0000000..38c24ca --- /dev/null +++ b/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 diff --git a/firmware/Makefile b/firmware/Makefile index f94e5fa..1d26c15 100644 --- a/firmware/Makefile +++ b/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\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 From bcbcb4d61c4049285433e9c587cd70014b41170e Mon Sep 17 00:00:00 2001 From: JMTamayo Date: Mon, 15 Jun 2026 17:32:53 -0500 Subject: [PATCH 2/2] ci: add firmware and provisioner CI workflows Firmware CI checks clang-format and builds with PlatformIO; provisioner CI checks ruff formatting and runs mypy. Both trigger on pull requests and pushes to main (path-filtered) and can be run manually via workflow_dispatch. Based on the frost-mind reference. --- .github/workflows/firmware-ci.yml | 55 ++++++++++++++++++++++++++++ .github/workflows/provisioner-ci.yml | 52 ++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 .github/workflows/firmware-ci.yml create mode 100644 .github/workflows/provisioner-ci.yml diff --git a/.github/workflows/firmware-ci.yml b/.github/workflows/firmware-ci.yml new file mode 100644 index 0000000..9957c81 --- /dev/null +++ b/.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 diff --git a/.github/workflows/provisioner-ci.yml b/.github/workflows/provisioner-ci.yml new file mode 100644 index 0000000..be638e5 --- /dev/null +++ b/.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