Sort and update template documentation. #39548
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe documentation for the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Documentation
User->>Documentation: Consults template integration reference
Documentation-->>User: Presents reorganized, clarified schema for all template entity platforms
User->>Documentation: Reviews configuration keys, descriptions, and defaults
Documentation-->>User: Provides consolidated, logically grouped, and updated information
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
source/_integrations/template.markdown (4)
167-170: Consolidate common fields into one map
Introducing[all sensor, binary sensor, button, image, light, number, select, switch, weather entities]reduces duplication. Fields inside should remain alphabetically sorted for consistency.Consider adding a brief note explaining this map covers all listed domains at once.
172-173: Tweak comma usage inavailabilitydescription
Grammar nit: add a comma after “fails to render” to improve readability.- If the template either fails to render or returns `True` + If the template either fails to render, or returns `True`🧰 Tools
🪛 LanguageTool
[misspelling] ~173-~173: This word is normally spelled with a hyphen.
Context: ... Note that the string comparison is not case sensitive;"TrUe"and"yEs"are allowed. ...(EN_COMPOUNDS_CASE_SENSITIVE)
277-277: Refinestatedescription punctuation
Add final period to meet markdown-lint rules.- ...depends on the sensor's device_class value + ...depends on the sensor's device_class value.🧰 Tools
🪛 LanguageTool
[style] ~277-~277: In American English, abbreviations like “etc.” require a period.
Context: ...nd (Open/Closed,Detected/Clearetc) depends on the sensor's device_class v...(ETC_PERIOD)
417-421: Addeffectfor lights
Defaultoptimisticmay surprise users; link to optimistic mode docs.Add reference to “Optimistic mode” section.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/template.markdown(16 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/template.markdown
[uncategorized] ~151-~151: Possible missing comma found.
Context: ...rs to update the entities. Optional. If omitted will update based on referenced entitie...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~159-~159: This expression is usually spelled with a hyphen.
Context: ...e configuration is loaded or reloaded. Trigger based template entities resolve variables bet...
(BASED_HYPHEN)
[misspelling] ~173-~173: This word is normally spelled with a hyphen.
Context: ... Note that the string comparison is not case sensitive; "TrUe" and "yEs" are allowed. ...
(EN_COMPOUNDS_CASE_SENSITIVE)
[uncategorized] ~190-~190: Possible missing comma found.
Context: ...with the unique ID of the configuration block if available. This allows changing the ...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~277-~277: In American English, abbreviations like “etc.” require a period.
Context: ...nd (Open/Closed, Detected/Clear etc) depends on the sensor's device_class v...
(ETC_PERIOD)
[uncategorized] ~311-~311: Possible missing comma found.
Context: ...pen). If the template produces a None value the current position will be set to `un...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~323-~323: Possible missing comma found.
Context: ...late. If the template produces a None value the state will be set to unknown. ...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~609-~609: Is an article like ‘a’ or ‘an’ missing?
Context: ... describes when the state of the sensor was last reset. Must render to a valid `dat...
(BE_NN)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/template.markdown
264-264: Emphasis style
Expected: underscore; Actual: asterisk
(MD049, emphasis-style)
264-264: Emphasis style
Expected: underscore; Actual: asterisk
(MD049, emphasis-style)
268-268: Emphasis style
Expected: underscore; Actual: asterisk
(MD049, emphasis-style)
268-268: Emphasis style
Expected: underscore; Actual: asterisk
(MD049, emphasis-style)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (77)
source/_integrations/template.markdown (77)
84-84: Simplify section title for clarity
The new header “State-based template (all platforms / domains)” concisely communicates that the configuration applies across all platforms, eliminating the need to enumerate them.
142-143: Moveactionsabove other keys
Reordering to listactionsfirst improves discoverability for trigger-based entities. Ensure this ordering is mirrored in UI schema docs.
150-151: Reordertriggersunder configuration
Listingtriggersimmediately afterconditionsaligns with logical flow: define when then what.🧰 Tools
🪛 LanguageTool
[uncategorized] ~151-~151: Possible missing comma found.
Context: ...rs to update the entities. Optional. If omitted will update based on referenced entitie...(AI_HYDRA_LEO_MISSING_COMMA)
159-159: Clarifyvariablesresolution timing
The updated description clearly differentiates load-time resolution for state-based entities from runtime resolution for trigger-based ones.🧰 Tools
🪛 LanguageTool
[uncategorized] ~159-~159: This expression is usually spelled with a hyphen.
Context: ...e configuration is loaded or reloaded. Trigger based template entities resolve variables bet...(BASED_HYPHEN)
176-176: Set default availability totrue
Defaulting availability to true is consistent with other integrations.
177-179: Reordericonfield
Alphabetical ordering placesiconbeforepicture.
181-182: Addpicturefield
Correctly followsicon, enhancing entity customization.
184-185: Addnamefield
Alphabetical placement is accurate.
186-188: Specifytype: templateforname
Ensures template rendering is explicit.
189-190: Addunique_idfield
Properly placed last in the common-fields map.🧰 Tools
🪛 LanguageTool
[uncategorized] ~190-~190: Possible missing comma found.
Context: ...with the unique ID of the configuration block if available. This allows changing the ...(AI_HYDRA_LEO_MISSING_COMMA)
192-193: Definetype: stringforunique_id
Matches established schema conventions.
194-194: Consolidate attribute templates
Introducing[all binary_sensor, sensor, vacuum entities]map is DRY and logical.
199-199: Addattributesmap
Allows multi-attribute templating in one block.
242-245: Adddisarmaction
Explicitdisarmimproves schema completeness.
246-249: Repositionstatetemplate
Moving state definition adjacent to actions enhances readability.
250-253: Addtriggeraction
Including atriggercallback is consistent with other template entities.
254-259: Switchbinary_sensorschema to list
Changing to list syntax matches other multi-entity configs. Update examples accordingly.
259-262: Addauto_offkey for binary sensors
Clarifies time-based auto-off behavior.
263-266: Introducedelay_off
Templated off-delay is a valuable addition.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
264-264: Emphasis style
Expected: underscore; Actual: asterisk(MD049, emphasis-style)
264-264: Emphasis style
Expected: underscore; Actual: asterisk(MD049, emphasis-style)
267-270: Introducedelay_on
Complementsdelay_offfor symmetric behavior.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
268-268: Emphasis style
Expected: underscore; Actual: asterisk(MD049, emphasis-style)
268-268: Emphasis style
Expected: underscore; Actual: asterisk(MD049, emphasis-style)
271-275: Adddevice_classwith default
DefaultNoneis appropriate for optional device typing.
293-296: Reorderclose_cover
Alpha ordering is correct; double–checkinclusiverequirement semantics.Verify
inclusiveusage in core schema docs.
305-309: Addoptimisticflag for covers
Optimistic mode consistency aids interactivity.
310-313: Introducepositiontemplate
Defines cover position. Ensure examples illustrate its use.🧰 Tools
🪛 LanguageTool
[uncategorized] ~311-~311: Possible missing comma found.
Context: ...pen). If the template produces aNonevalue the current position will be set to `un...(AI_HYDRA_LEO_MISSING_COMMA)
322-325: Reorderstatetemplate
Grouping state with position and tilt improves schema clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~323-~323: Possible missing comma found.
Context: ...late. If the template produces aNonevalue the state will be set tounknown. ...(AI_HYDRA_LEO_MISSING_COMMA)
326-329: Addstop_coveraction
Completes cover control actions set.
334-338: Addtilt_optimistic
Aligns cover tilt with optimistic interactivity.
344-347: Addoscillatingtemplate
Supports new fan oscillation state.
348-350: Adddirectiontemplate
Allows forward/reverse fan control.
360-364: Convertpreset_modesto list
Default empty list is clearer than a single string or list union.
386-397: Reorder fanstate,turn_on,turn_off
Mandatory fields first, followed by optional presets, is logical.
422-426: Addeffect_listfor lights
Templates for supported effects is a useful extension.
437-441: Addmin_miredstemplate
Defines min color temperature; ordering is alphabetical.
442-446: Addmax_miredstemplate
Complementsmin_mireds.
462-465: Addset_effectaction
Marksset_effectas inclusive witheffect; ensure example YAML reflects inclusion.Check sample configs for proper
inclusiveusage.
490-494: Reintroducestatewith default
Default optimistic state fits interactive entity patterns.
495-499: Addsupports_transition
Clarifies transition capability; default false is safe.
500-504: Addtemperaturetemplate
Defaultoptimisticmay conflict with other defaults; verify its intent.Confirm default for
temperatureis intended to beoptimistic.
505-508: Reorderturn_onfor lights
Placing mandatory actions next improves readability.
527-530: Addopenaction to locks
Extends lock control; verify core supports this verb.Search for
async_openin template lock implementation.
531-535: Introduceoptimisticfor locks
Optimistic mode is consistent.
536-539: Addstatetemplate for locks
Required state template aligns with other entities.
549-553: Reordermaxfor numbers
Alphabetical and logical; default 100.0 is reasonable.
554-558: Addminfor numbers
Defines lower bound; default 0.0 is sensible.
559-563: Addoptimisticfor numbers
Matches pattern for interactive helpers.
564-567: Introduceset_valueaction
Essential for number controls; marked required correctly.
568-571: Addstatetemplate for numbers
Required state definition; description is clear.
572-576: Addunit_of_measurementdefault
DefaultNonematches optional units.
577-581: Addsteptemplate
Defines increment step; required is appropriate.
586-590: Addoptimisticfor selects
Consistent with select interactivity.
591-594: Addoptionstemplate
Defining choices is core to select; required flag is correct.
595-598: Addselect_optionaction
Completes selection workflow.
599-602: Addstatetemplate for selects
Required for reflecting current selection.
608-612: Addlast_resettemplate
Useful for sensors withstate_class=total; defaultNoneis fine.🧰 Tools
🪛 LanguageTool
[grammar] ~609-~609: Is an article like ‘a’ or ‘an’ missing?
Context: ... describes when the state of the sensor was last reset. Must render to a valid `dat...(BE_NN)
613-616: Addstatetemplate for sensors
Enforces numeric output for templated sensors; description covers edge cases.
617-621: Introducestate_class
Optional key supports long-term statistics; defaultNoneis standard.
622-626: Addunit_of_measurementdefault
Aligns with sensor conventions.
641-644: Reorderturn_onfor switches
Ensures mandatory actions are clearly listed.
654-657: Addclean_spotaction
Complements vacuum feature set.
662-665: Introducefan_speedslist
Allowing multiple speeds is logical.
666-669: Addlocateaction
Useful for vacuum finding routines.
682-685: Markstartaction as required
Good to mandate initial cleaning command.
686-689: Addstatetemplate for vacuums
Describes all valid vacuum states.
690-693: Addstopaction
Completes vacuum control API.
699-702: Addapparent_temperature_template
Increases weather data fidelity.
703-706: Addcloud_coverage_template
Enhances cloud reporting.
715-718: Addforecast_daily_template
Logical daily forecast granularity.
719-722: Addforecast_hourly_template
Supports hourly forecasts.
723-726: Addforecast_twice_daily_template
Adds twice-daily forecast slots.
731-734: Addozone_template
Completes pollution metrics.
735-738: Addprecipitation_unit
Specifies unit expectations.
763-766: Addwind_gust_speed_template
Captures gust data.
767-770: Addwind_speed_template
Core wind metric.
771-774: Addwind_speed_unit
Specifies wind speed units.
775-778: Addwind_bearing_template
Provides directional wind info.
154-157:❓ Verification inconclusive
Reposition
unique_id
Movingunique_idaftertriggersgroups all identification and update settings together. Verify no tooling expects a different key order.Run:
to confirm no ordering assumptions.
🏁 Script executed:
rg -n 'unique_id:' -n source/_integrations/template.markdownLength of output: 319
Verify relocation of
unique_id
Relocating the top-levelunique_id(currently at line 154) to immediately followtriggerswill group all identification and update settings—but make sure no tooling or docs generator depends on the existing key order.Occurrences of
unique_id:in this file: lines 154, 189, 907, 1221, 1273, 1292, 1344, 1427.Run:
rg -n 'triggers:' source/_integrations/template.markdown rg -n 'unique_id:' source/_integrations/template.markdown
216-220:❓ Verification inconclusive
Insert
arm_custom_bypassaction
Adding this action aligns ordering alphabetically. Confirm the core integration implements this bypass mode.Search implementation:
🏁 Script executed:
rg 'arm_custom_bypass' -n homeassistant/components/templateLength of output: 133
🏁 Script executed:
#!/bin/bash # Search the entire repository for any reference to arm_custom_bypass rg -n 'arm_custom_bypass'Length of output: 1427
🏁 Script executed:
#!/bin/bash # Verify Template Alarm Control Panel implementation for arm_custom_bypass rg -n 'arm_custom_bypass' -n homeassistant/components/alarm_control_panel rg -n 'custom_bypass' -n homeassistant/components/alarm_control_panelLength of output: 313
Confirm
arm_custom_bypasssupport in core Template Alarm Control Panel
I couldn’t find any implementation ofarm_custom_bypassin the Home Assistant core (e.g. underhomeassistant/components/templateoralarm_control_panel/template.py). Please verify that the Template Alarm Control Panel integration in core actually implements this action before merging.
Proposed change
Correct mistakes in the variable documentation.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit