Contributing

Thanks for contributing to aioafero.

Getting started

  1. Fork and clone the repository.

  2. Install Python 3.12+ (3.12, 3.13, and 3.14 are tested in CI).

  3. Sync dev dependencies:

    uv sync --extra test

  4. Run lint and tests before opening a PR — see Testing and CI.

Pull request checklist

uv run tox -e lint
uv run tox run-parallel -p auto -o --skip-env lint
uv run tox -e docs   # if you touched anything under docs/ or public APIs

Report bugs and feature requests on GitHub Issues.

Code layout

  • src/aioafero/ — library source

  • src/aioafero/v1/ — v1 API bridge, auth, controllers, models

  • tests/ — pytest suite (mirrors src/ layout)

Device and protocol logic belongs in aioafero, not downstream Home Assistant integrations. Add new API behavior here first, then wrap it in Hubspace-Homeassistant.

Documentation

Hand-written guides and autogenerated API reference live under docs/. Published site: https://aioafero.readthedocs.io/. Hubspace app HTTPS capture for reverse engineering lives under MITM capture setup.

Layout

  • docs/index.rst — documentation home and sidebar toctree

  • docs/user/ — user guide (overview, auth, bridge, examples, troubleshooting, …)

  • docs/user/controllers/ — per-controller pages (mostly autoclass from source)

  • docs/api/ — generated on each build by sphinx-apidoc; do not edit by hand

  • CHANGELOG.rst — user-visible changes; included in the docs via docs/changelog.rst

Add a new user-guide page to the .. toctree:: under User guide in docs/index.rst.

When to update docs

Update documentation in the same PR when you change behavior that users or integrators rely on:

  • Public API (bridge/auth signatures, controller methods, errors) — update the relevant docs/user/ page and add a CHANGELOG.rst entry for breaking or notable changes.

  • New user-guide topic — add docs/user/<topic>.rst and link it from the toctree and related pages.

  • Controller-only internals — autodoc may be enough; skip narrative docs unless the public surface changed.

Diagrams in the user guide use Mermaid (.. mermaid:: blocks). Requires the docs optional extra (sphinxcontrib-mermaid).

Build and preview

CI and the PR checklist use tox -e docs (warnings are errors). From a dev checkout with the test extra installed:

uv sync --extra test
uv run tox -e docs

tox runs sphinx-build in an isolated env with the docs extra — you do not need uv sync --extra docs for that path.

For faster iteration while editing RST files, sync docs and call Sphinx directly:

uv sync --extra docs
uv run sphinx-build -W -b html docs docs/_build/html

Open docs/_build/html/index.html in a browser, or serve the tree locally:

cd docs/_build/html && python -m http.server 8000

Then browse http://localhost:8000/ (user guide pages are under /user/).

Hosted docs are rebuilt when the Publish workflow runs after a release; until then, main on GitHub may be ahead of what you see on Read the Docs — use a local build to review doc changes before merge.