mirror of
https://github.com/cassandra/home-information.git
synced 2026-06-12 01:25:39 -04:00
8314eced6e
Establishes a two-track per-integration doc structure (user-facing under docs/integrations/, developer-facing under docs/dev/integrations/) with templates that enforce a consistent set of sections for each integration. Populates the new structure for the three existing user-configured integrations (Home Assistant, ZoneMinder, HomeBox) and updates the integration-addition guideline to require both docs for any new integration. User-facing changes: - New per-integration pages with overview, prerequisites, credential acquisition, configuration values, setup walkthrough, troubleshooting, and known limitations. ZoneMinder's existing CORS and HTTPS/SSL troubleshooting content migrated out of the shared Integrations.md into its own page. - Restructured docs/Integrations.md as a short landing page that centralizes the conditional UI flow for enabling an integration (different button label and location depending on whether any are configured yet) so per-integration pages can link to it instead of restating it. - Conventions documented in the user-facing template: introduce Home Information (HI) on first mention; use 'item' for HI's representation, reserve 'entity' for upstream services that use that term; use 'Import' (first run) and 'Refresh' (subsequent), not 'sync', in user-facing copy. Developer-facing changes: - New per-integration dev docs for ZoneMinder and HomeBox; HA dev doc expanded from a single section to all six required sections. - Dev template explicitly directs writers to keep content high-level and refer to the code for details; existing dev docs follow that principle (key modules listed with one-line roles, no method signatures or field lists duplicated). - Weather integration doc gets a one-paragraph preface marking it as an internal-source exception that does not follow the per-integration template structure. Simulator documentation: - docs/dev/testing/test-simulator.md expanded to cover the simulator's purpose and architecture, the URL mappings for pointing each HI integration at the simulator, and the seed_sim_profiles command (with a profile summary table and a pointer to the command's docstring for the full operator workflow).
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
<!--
|
|
TEMPLATE — copy this file to docs/dev/integrations/<integration-name>.md
|
|
and fill in each section.
|
|
|
|
Goal: orient a developer who has never read this integration's code
|
|
before. Keep it high-level and point at the code for details — the
|
|
code is the authoritative source. Do not duplicate class signatures,
|
|
method bodies, or field lists; the moment those drift, the doc
|
|
starts misleading. Refer to file paths and class names instead.
|
|
-->
|
|
|
|
# <Integration Name>
|
|
|
|
## Overview
|
|
|
|
One paragraph on the integration's architecture: what major pieces
|
|
exist (gateway, manager, sync, monitors, client) and how they fit
|
|
together. Mention how this integration's shape differs from the
|
|
generic pattern in `integration-guidelines.md` if at all.
|
|
|
|
## Key modules
|
|
|
|
A short list of the most important files and classes a new
|
|
contributor should know about, each with a one-line description of
|
|
its role. Do not enumerate every file — pick the entry points.
|
|
|
|
- `src/hi/services/<name>/<file>.py` — `<ClassName>`. <One-line role>.
|
|
- `src/hi/services/<name>/<file>.py` — `<ClassName>`. <One-line role>.
|
|
|
|
## API patterns
|
|
|
|
Which external endpoints the integration depends on, the
|
|
authentication model, and any rate-limiting or polling cadence
|
|
considerations. State the shape; do not paste request/response bodies
|
|
(those belong in test fixtures or upstream docs).
|
|
|
|
## Implementation notes
|
|
|
|
Non-obvious decisions, workarounds, and quirks of the upstream service
|
|
that influenced the implementation. This is the section future-you
|
|
will be most grateful for. Examples of what belongs here:
|
|
|
|
- Why a specific endpoint is preferred over an obvious alternative.
|
|
- Quirks in the upstream API (inconsistent field names, eventual
|
|
consistency windows, undocumented limits).
|
|
- Tradeoffs taken in the converter (heuristics, fallbacks).
|
|
|
|
## Testing approach
|
|
|
|
Where tests live and the mocking patterns used. If there is simulator
|
|
support for this integration, mention where (`src/hi/simulator/services/<name>/`)
|
|
and what it covers. Manual testing notes belong in
|
|
`docs/dev/testing/test-simulator.md`, not here.
|
|
|
|
## References
|
|
|
|
Links to upstream API documentation and any related internal docs.
|
|
|
|
- Upstream: <link>
|
|
- Related: <link to related internal doc, if any>
|