jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-05-28 18:43:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: document entity reference system in AGENTS.md

Browse source 
Add documentation for the new multi-language entity reference system:
- Generator script usage (generate-sensor-reference, --check mode)
- Entity reference annotation guidelines for doc pages
- Updated scripts/check description to include reference freshness
- Reminder to regenerate reference after adding/renaming entities

Impact: Future sessions know how to maintain the entity reference
system and keep it in sync with translation file changes.
This commit is contained in:
Julian Pawlowski 2026-04-11 09:56:10 +00:00
parent 0e699ae142
commit c892d7376c
1 changed files with 12 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
AGENTS.md
View file

@ -843,7 +843,14 @@ If you notice commands failing or missing dependencies:
./scripts/type-check # Run Pyright type checking ./scripts/type-check # Run Pyright type checking
./scripts/lint-check # Run Ruff linting (check-only, CI mode) ./scripts/lint-check # Run Ruff linting (check-only, CI mode)
./scripts/lint # Run Ruff linting with auto-fix ./scripts/lint # Run Ruff linting with auto-fix
./scripts/check # Run both type-check + lint-check (recommended before commits) ./scripts/check # Run both type-check + lint-check + sensor reference freshness (recommended before commits)
```
**Documentation generation:**
```bash
./scripts/docs/generate-sensor-reference # Regenerate sensor-reference.md from translation files
./scripts/docs/generate-sensor-reference --check # Verify reference is current (used in CI)
``` ```
**Local validation:** **Local validation:**
@ -2098,6 +2105,8 @@ Public entry points → direct helpers (call order) → pure utilities. Prefix p
- **UI translations**: Multi-language support exists in `/translations/` and `/custom_translations/` (de, en, nb, nl, sv) for UI strings only - **UI translations**: Multi-language support exists in `/translations/` and `/custom_translations/` (de, en, nb, nl, sv) for UI strings only
- **Why English-only docs**: Ensures maintainability, accessibility to global community, and consistency with Home Assistant ecosystem - **Why English-only docs**: Ensures maintainability, accessibility to global community, and consistency with Home Assistant ecosystem
- **Entity names in documentation**: Use **translated display names** from `/translations/en.json` (what users see), not internal entity IDs. Example: "Best Price Period" not "sensor.tibber_home_best_price_period" (add entity ID as comment if needed for clarity). - **Entity names in documentation**: Use **translated display names** from `/translations/en.json` (what users see), not internal entity IDs. Example: "Best Price Period" not "sensor.tibber_home_best_price_period" (add entity ID as comment if needed for clarity).
- **Entity reference annotations**: When mentioning entity display names in docs, add the `translation_key` (= entity ID suffix) on first mention per section: `**Display Name** (\`translation_key\`)`. This helps users find entities regardless of UI language. See `docs/user/docs/sensor-reference.md` for the auto-generated multi-language lookup table.
- **Entity ID tip boxes**: All doc pages with entity ID examples should include the standardized tip box linking to `sensor-reference.md`. Use the same wording as in existing pages (search for "Entity ID tip" for the template).
**Examples and use cases:** **Examples and use cases:**
@ -2708,6 +2717,8 @@ After the sensor.py refactoring (completed Nov 2025), sensors are organized by *
- **Volatility**: Statistical analysis of price variation - **Volatility**: Statistical analysis of price variation
- **Diagnostic**: System information and metadata - **Diagnostic**: System information and metadata
**IMPORTANT — After adding/renaming entities**: Run `./scripts/docs/generate-sensor-reference` to regenerate the multi-language sensor reference table. The `scripts/check` and CI will fail if the reference is stale.
2. **Add entity description** to appropriate sensor group in `sensor/definitions.py`: 2. **Add entity description** to appropriate sensor group in `sensor/definitions.py`:
- `INTERVAL_PRICE_SENSORS`, `INTERVAL_LEVEL_SENSORS`, or `INTERVAL_RATING_SENSORS` - `INTERVAL_PRICE_SENSORS`, `INTERVAL_LEVEL_SENSORS`, or `INTERVAL_RATING_SENSORS`