From 6fb2130ace0ec7f8b63418006f3c1c367fe6b75d Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Tue, 12 May 2026 10:29:58 -0700 Subject: [PATCH 1/5] ci: migrate docs deployment to GitHub Actions Pages Replace mkdocs gh-deploy (push-to-branch) with the official actions/upload-pages-artifact + actions/deploy-pages workflow. Changes: - Drop contents:write permission (no longer pushing to gh-pages branch) - Add pages:write and id-token:write for OIDC-based deployment - Split into build/deploy jobs for clearer separation of concerns - Add concurrency guard to prevent overlapping deployments - Add --strict flag to mkdocs build to catch doc warnings as errors After merging, change GitHub Pages source to 'GitHub Actions' in: Settings > Pages > Build and deployment > Source --- .github/workflows/docs.yml | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c02f74e..0669a2b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -6,10 +6,16 @@ on: workflow_dispatch: permissions: - contents: write + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false jobs: - build-and-deploy: + build: runs-on: ubuntu-latest steps: - name: Checkout @@ -24,15 +30,20 @@ jobs: run: pip install ".[docs]" - name: Build documentation - run: mkdocs build + run: mkdocs build --strict - - name: Ensure .nojekyll in site - run: touch site/.nojekyll + - name: Upload pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site/ + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: - name: Deploy to GitHub Pages - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - git config --global user.name "github-actions[bot]" - git config --global user.email "github-actions[bot]@users.noreply.github.com" - mkdocs gh-deploy --force --clean --remote-branch gh-pages + id: deployment + uses: actions/deploy-pages@v4 From 23d18b9bfbdb13110cc3cba050c47ecbfbd16fdd Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Tue, 12 May 2026 10:40:09 -0700 Subject: [PATCH 2/5] docs: remove LLM-tell phrases and filler language - cli_guide: remove 'modern, user-friendly', 'beautiful terminal output', 'intuitive command structure' - control_modes guide: 'comprehensive information' -> 'covers' - protocol/control_modes: 'comprehensive overview' -> 'covers' - protocol/schedules: 'includes comprehensive validation' -> 'validates' - protocol/architecture: 'unlock the pump's capabilities' -> factual description - TESTING_STRATEGY: 'comprehensive testing strategy, designed to ensure' -> direct - reference/data_models: 'with comprehensive validation' -> factual note - api/constants: 'comprehensive lookup table' -> 'lookup table' --- docs/TESTING_STRATEGY.md | 2 +- docs/api/constants.md | 2 +- docs/guides/cli_guide.md | 2 +- docs/guides/control_modes.md | 2 +- docs/protocol/architecture.md | 2 +- docs/protocol/control_modes.md | 2 +- docs/protocol/schedules.md | 2 +- docs/reference/data_models.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md index 8eb4b50..25a2925 100644 --- a/docs/TESTING_STRATEGY.md +++ b/docs/TESTING_STRATEGY.md @@ -2,7 +2,7 @@ ## Overview -This document outlines the comprehensive testing strategy for the alpha-hwr library, designed to ensure reliability, maintainability, and serve as a reference for other language implementations. +This document outlines the testing strategy for the alpha-hwr library, covering reliability, maintainability, and serving as a reference for other language implementations. ## Testing Pyramid diff --git a/docs/api/constants.md b/docs/api/constants.md index b98be8c..78be1a4 100644 --- a/docs/api/constants.md +++ b/docs/api/constants.md @@ -69,7 +69,7 @@ Addresses for Legacy Class 3 Register Polling. ## ERROR_CODES (Dictionary) -A comprehensive lookup table mapping error codes to human-readable descriptions. Extracted from the GENI profile. +A lookup table mapping error codes to human-readable descriptions. Extracted from the GENI profile. ```python from alpha_hwr.constants import ERROR_CODES diff --git a/docs/guides/cli_guide.md b/docs/guides/cli_guide.md index 98cd5bc..3c2e690 100644 --- a/docs/guides/cli_guide.md +++ b/docs/guides/cli_guide.md @@ -1,6 +1,6 @@ # Command Line Interface (CLI) Guide -The `alpha-hwr` command-line tool provides a modern, user-friendly interface for interacting with your Grundfos ALPHA HWR pump. Built with Typer and Rich, it offers beautiful terminal output and intuitive command structure. +The `alpha-hwr` command-line tool for interacting with Grundfos ALPHA HWR pumps. Built on Typer and Rich. ## Table of Contents diff --git a/docs/guides/control_modes.md b/docs/guides/control_modes.md index 3622bea..04f020f 100644 --- a/docs/guides/control_modes.md +++ b/docs/guides/control_modes.md @@ -1,6 +1,6 @@ # Control Modes and Setpoints -This guide provides comprehensive information about the ALPHA HWR's control modes and setpoint configuration. +This guide covers the ALPHA HWR's control modes and setpoint configuration. ## Overview diff --git a/docs/protocol/architecture.md b/docs/protocol/architecture.md index f9f6835..42f21a6 100644 --- a/docs/protocol/architecture.md +++ b/docs/protocol/architecture.md @@ -21,7 +21,7 @@ graph TD ## 2. Authentication Sequence -The authentication process is a strict sequence of "magic packets" required to unlock the pump's capabilities. +The authentication process is a strict sequence of "magic packets" that must succeed before the pump accepts commands. ```mermaid sequenceDiagram diff --git a/docs/protocol/control_modes.md b/docs/protocol/control_modes.md index c9f17bc..690952d 100644 --- a/docs/protocol/control_modes.md +++ b/docs/protocol/control_modes.md @@ -1,6 +1,6 @@ # Control Modes - Complete Support Matrix -This document provides a comprehensive overview of all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump. +This document covers all 32 control modes defined in the GENI protocol and their support status on the Grundfos ALPHA HWR pump. ## Executive Summary diff --git a/docs/protocol/schedules.md b/docs/protocol/schedules.md index e9f9647..63c317d 100644 --- a/docs/protocol/schedules.md +++ b/docs/protocol/schedules.md @@ -613,7 +613,7 @@ alpha-hwr schedule ## Schedule Validation -The library includes comprehensive validation for schedule entries to prevent conflicts and errors. +The library validates schedule entries to prevent conflicts and errors. ### ScheduleEntry Model diff --git a/docs/reference/data_models.md b/docs/reference/data_models.md index c9fe1a1..7764937 100644 --- a/docs/reference/data_models.md +++ b/docs/reference/data_models.md @@ -154,7 +154,7 @@ if alarms: ## ScheduleEntry Model -The `ScheduleEntry` class represents a single schedule time window with comprehensive validation. +The `ScheduleEntry` class represents a single schedule time window. All fields are validated on construction. ### Properties From 28229d776d264e08bcd49104949cac314e9111df Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Tue, 12 May 2026 11:42:39 -0700 Subject: [PATCH 3/5] docs: add Home Assistant / ESPHome proxy recommendation to README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index d3cdbc7..e62e894 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,10 @@ async with AlphaHWRClient(address) as client: Actively maintained and tested on real ALPHA HWR hardware. +## Home Assistant + +For Home Assistant integration, use the ESPHome component instead of this library: [esphome-alpha-hwr](https://github.com/eman/esphome-alpha-hwr). It runs on an ESP32 as a Bluetooth proxy, exposing the pump as native Home Assistant sensors without requiring a Python host. + ## Contributing Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. From 51e47009cbb14ebba793ede4be97795d322f2398 Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Tue, 12 May 2026 11:45:15 -0700 Subject: [PATCH 4/5] update to say suggested --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e62e894..e3f131d 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ Actively maintained and tested on real ALPHA HWR hardware. ## Home Assistant -For Home Assistant integration, use the ESPHome component instead of this library: [esphome-alpha-hwr](https://github.com/eman/esphome-alpha-hwr). It runs on an ESP32 as a Bluetooth proxy, exposing the pump as native Home Assistant sensors without requiring a Python host. +For Home Assistant integration, it is suggested to use the ESPHome component instead of this library: [esphome-alpha-hwr](https://github.com/eman/esphome-alpha-hwr). It runs on an ESP32 as a Bluetooth proxy, exposing the pump as native Home Assistant sensors without requiring a Python host. ## Contributing From 31967acdcd3a7e169d95de3f39a4b0add612cffa Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Tue, 12 May 2026 12:49:16 -0700 Subject: [PATCH 5/5] review comments --- .github/workflows/docs.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0669a2b..b27cd4f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,11 +5,6 @@ on: branches: [main] workflow_dispatch: -permissions: - contents: read - pages: write - id-token: write - concurrency: group: pages cancel-in-progress: false @@ -17,6 +12,8 @@ concurrency: jobs: build: runs-on: ubuntu-latest + permissions: + contents: read steps: - name: Checkout uses: actions/checkout@v4 @@ -40,6 +37,9 @@ jobs: deploy: needs: build runs-on: ubuntu-latest + permissions: + pages: write + id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }}