Improve schedule documentation #37104
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe pull request updates the documentation for the Home Assistant Schedule integration, focusing on improving content clarity and structure. The changes enhance the explanation of configuration options, including new entries for Name, Icon, and Schedule blocks. The documentation now provides more detailed guidance on setting up schedules, with a clearer emphasis on YAML configuration and a more explicit description of schedule block attributes and additional data. Changes
Sequence DiagramsequenceDiagram
participant User
participant HomeAssistant
participant ScheduleIntegration
User->>HomeAssistant: Configure Schedule
HomeAssistant->>ScheduleIntegration: Define Schedule Blocks
ScheduleIntegration-->>HomeAssistant: Validate Configuration
HomeAssistant-->>User: Apply Schedule Settings
The sequence diagram illustrates the basic flow of configuring a schedule in Home Assistant, showing how users define schedule blocks through the integration, which are then validated and applied by the system. Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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 (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
source/_integrations/schedule.markdown (4)
17-17: Fix grammatical error in button reference.Remove the article "the" before "My button" as it's part of the button name.
-To add a schedule to your Home Assistant Instance, use the My button below. +To add a schedule to your Home Assistant Instance, use My button below.🧰 Tools
🪛 LanguageTool
[grammar] ~17-~17: Possible typo. Did you mean “the” or “My”?
Context: ...le to your Home Assistant Instance, use the My button below. {% include integrations/...(DT_PRP)
49-51: Consider adding an inline example for Additional data mapping.While the concept is explained well, adding a simple inline example would make it immediately clear to users.
The **Additional data** entry of each block should be a mapping of attribute names to values. For example, the schedule helper entity could have `brightness` and `color_temp` attributes when the blocks are active. +For instance: +```yaml +Additional data: + brightness: 100 + color_temp: 4000 +```
57-57: Improve clarity of the Additional data explanation.The sentence about additional data could be more explicit.
-Additional data can be added as `data` block mapping for each schedule block. +Additional data can be added using the `data` block for each schedule block, as shown in the example below:
129-129: Remove unnecessary comma in attributes description.For better readability, remove the comma before "when".
-| Additional data | The entries in **Additional data** / `data` of a schedule block, when the respective block is active. | +| Additional data | The entries in **Additional data** / `data` of a schedule block when the respective block is active. |🧰 Tools
🪛 LanguageTool
[typographical] ~129-~129: Usually, there’s no comma before “when”.
Context: ...onal data** /dataof a schedule block, when the respective block is active. | ## A...(IF_NO_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(2 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/schedule.markdown
[grammar] ~17-~17: Possible typo. Did you mean “the” or “My”?
Context: ...le to your Home Assistant Instance, use the My button below. {% include integrations/...
(DT_PRP)
[typographical] ~129-~129: Usually, there’s no comma before “when”.
Context: ...onal data** / data of a schedule block, when the respective block is active. | ## A...
(IF_NO_COMMA)
🔇 Additional comments (1)
source/_integrations/schedule.markdown (1)
15-15: Documentation structure and clarity improvements look great!The enhanced documentation structure with clear sections for UI configuration, YAML setup, and automation examples makes it easier for users to understand and implement schedules. The addition of detailed configuration options and explicit descriptions for each component is particularly helpful.
Also applies to: 21-47
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
source/_integrations/schedule.markdown (1)
153-153:⚠️ Potential issueFix syntax error in automation example.
There's a missing closing quote in the template expression for
kelvin.- kelvin: "{{ state_attr('schedule.light_schedule, 'temperature') }}" + kelvin: "{{ state_attr('schedule.light_schedule', 'temperature') }}"
🧹 Nitpick comments (2)
source/_integrations/schedule.markdown (2)
30-30: Fix grammatical issues.There are several grammatical issues that need to be addressed:
-After you have created schedule blocks, you can use a **single left click** on a block to open an edit view for a this time block. +After you have created schedule blocks, you can use a **single left click** on a block to open an edit view for this time block. -The **Additional data** entry of each block should be a mapping of attribute names to values. For example, a block with the the following data will show `brightness` and `color_temp` as {% term entity %} attributes when the blocks is active: +The **Additional data** entry of each block should be a mapping of attribute names to values. For example, a block with the following data will show `brightness` and `color_temp` as {% term entity %} attributes when the block is active:Also applies to: 47-48
🧰 Tools
🪛 LanguageTool
[grammar] ~30-~30: Two determiners in a row. Choose either “a” or “this”.
Context: ...k** on a block to open an edit view for a this time block. {% configuration_basic %}...(DT_DT)
136-136: Remove trailing whitespace.There's a trailing whitespace at the end of this line.
-A schedule creates an on/off (schedule) sensor within the times set. +A schedule creates an on/off (schedule) sensor within the times set.🧰 Tools
🪛 Markdownlint (0.37.0)
136-136: Expected: 0 or 2; Actual: 1
Trailing spaces(MD009, no-trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(3 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/schedule.markdown
[grammar] ~30-~30: Two determiners in a row. Choose either “a” or “this”.
Context: ...k** on a block to open an edit view for a this time block. {% configuration_basic %}...
(DT_DT)
[duplication] ~48-~48: Possible typo: you repeated a word.
Context: ...es to values. For example, a block with the the following data will show brightness a...
(ENGLISH_WORD_REPEAT_RULE)
[uncategorized] ~48-~48: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...s {% term entity %} attributes when the blocks is active: ```yaml brightness: 100 col...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[grammar] ~48-~48: “blocks” is a plural noun. It appears that the verb form is incorrect.
Context: ...rm entity %} attributes when the blocks is active: ```yaml brightness: 100 color_...
(PCT_PLURAL_NOUN_SINGULAR_VERB_AGREEMENT)
🪛 Markdownlint (0.37.0)
source/_integrations/schedule.markdown
136-136: Expected: 0 or 2; Actual: 1
Trailing spaces
(MD009, no-trailing-spaces)
⏰ 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 (2)
source/_integrations/schedule.markdown (2)
15-28: LGTM! Clear and well-structured introduction.The introduction and basic configuration section effectively explains the Schedule integration's purpose and setup process.
Line range hint
55-124: LGTM! Comprehensive YAML configuration documentation.The YAML configuration section provides clear examples and a complete configuration schema.
🧰 Tools
🪛 LanguageTool
[grammar] ~30-~30: Two determiners in a row. Choose either “a” or “this”.
Context: ...k** on a block to open an edit view for a this time block. {% configuration_basic %}...(DT_DT)
[duplication] ~48-~48: Possible typo: you repeated a word.
Context: ...es to values. For example, a block with the the following data will showbrightnessa...(ENGLISH_WORD_REPEAT_RULE)
[uncategorized] ~48-~48: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...s {% term entity %} attributes when the blocks is active: ```yaml brightness: 100 col...(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[grammar] ~48-~48: “blocks” is a plural noun. It appears that the verb form is incorrect.
Context: ...rm entity %} attributes when the blocks is active: ```yaml brightness: 100 color_...(PCT_PLURAL_NOUN_SINGULAR_VERB_AGREEMENT)
Co-authored-by: Simon Lamon <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
source/_integrations/schedule.markdown (5)
19-28: Enhanced Configuration Block for Core ParametersThe new configuration block for Name, Icon, and Schedule blocks offers clear, user-friendly directives.
Note: There is a trailing space on line 21 that should be removed to comply with markdownlint (MD009).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
21-21: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
32-45: Detailed Timing and Additional Data ConfigurationThis block clearly specifies required fields for "Start" and "End" times and provides an optional mapping for "Additional data."
Recommendation: Consider clarifying the expected time format (e.g., HH:MM or HH:MM:SS) to avoid ambiguity.
47-47: Clarification on Additional Data MappingReiterating that additional data should be a mapping reinforces its intended structure.
Optional: Verify if this repetition is intentional or if a cross-reference to the description in the configuration block would suffice.
125-133: Clear and Concise Attributes DocumentationThe attributes section succinctly outlines how a schedule entity exports its attributes, including the additional data mapping.
Optional: Consider elaborating slightly more on the "Additional data" attribute to match the detail provided elsewhere in the documentation.
134-154: Updated Automation Example for Schedule ActivationThe first automation example accurately shows how to trigger actions (e.g., light turning on) when the schedule activates. The templating for
brightness_pctandkelvin(correctly referencing temperature) is implemented well.
Optional: Adding a brief explanatory note before the code block could further improve clarity for users.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/schedule.markdown
21-21: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🔇 Additional comments (5)
source/_integrations/schedule.markdown (5)
15-15: Clear and Concise Schedule IntroductionThe updated introduction effectively defines the schedule's functionality and how time blocks activate and deactivate.
30-30: Precise Editing Instruction AddedThe added line clearly instructs users that after creating schedule blocks, they can press a block to edit its details.
51-52: Effective YAML Example for Additional DataThe YAML snippet clearly demonstrates how to specify attributes like
brightnessandcolor_temp.
55-60: Improved Guidance for YAML ConfigurationThe revised section provides clear instructions for manual YAML-based setup and mentions the use of a
datablock for each schedule block.
156-173: Clear Automation Example for Schedule DeactivationThe second automation example effectively demonstrates how to trigger actions when the schedule turns off.
|
Thanks for the review! Added most of your suggestions directly, please double check if the remaining review points are formulated better now. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
source/_integrations/schedule.markdown (1)
21-21: Remove Trailing Whitespace.
There is a trailing space at the end of the description on line 21. Removing this extra space will comply with markdown lint rules (MD009).- description: Friendly name of the schedule. + description: Friendly name of the schedule.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
21-21: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/schedule.markdown
21-21: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🔇 Additional comments (11)
source/_integrations/schedule.markdown (11)
15-15: Clear and Informative Introduction.
The new introductory paragraph on line 15 effectively explains what the Schedule integration is and how it functions, setting a clear context for the reader.
19-28: Well-Structured Basic Configuration Block.
The configuration block for the basic settings (Name, Icon, and Schedule blocks) is clear and easy to follow. The descriptions provide sufficient guidance for setting up the schedule through the UI.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
21-21: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
30-30: Concise UI Instruction Addition.
The newly added instruction on line 30—informing users that they can press a schedule block to edit its details—is clear and enhances the documentation's usability.
32-45: Comprehensive Parameter Configuration.
This configuration block for "Start," "End," and "Additional data" clearly specifies the requirements and data types for each parameter. The descriptions help users understand how these fields affect the schedule's behavior.
47-48: Clear Explanation of Additional Data.
The explanation provided on lines 47–48 reinforces that the "Additional data" entry should be a mapping of attribute names to values, which is useful for conveying how the schedule affects entity attributes when active.
51-52: Effective YAML Example for Additional Data.
The YAML snippet on lines 51–52, demonstrating how to set attributes likebrightnessandcolor_temp, is simple and clear. It successfully shows users the expected format for additional data.
57-60: Enhanced YAML Configuration Instructions.
The updated instructions on lines 57–60, which explain how to manually configure the integration via YAML, are now more explicit and user-friendly. This alternate setup guidance will help users who prefer manual configuration.
131-131: Clarification of Exported Attributes.
The updated table entry on line 131 clearly details that the keys (e.g.,key_1,key_2) are derived from the Additional data/datasetting. This clarification improves the reader’s understanding of how schedule block data maps to entity attributes.
133-137: Improved Automation Example Introduction.
The revised introduction to the automation example (lines 133–137) succinctly explains the purpose of the schedule sensor in automations, helping users understand when and how the schedule activates the sensor.
142-152: Corrected Automation Example Syntax.
The first automation example now correctly utilizes thestate_attrfunction with proper quoting in its YAML snippet, particularly for the "kelvin" attribute. This helps prevent syntax issues and ensures that the example is accurate.
161-171: Consistent Off-Automation Example.
The second automation example (lines 161–171) mirrors the structure and clarity of the first, effectively demonstrating how to turn off a light when the schedule becomes inactive.
|
I've marked this PR as a draft, as changes are requested that need to be processed. Thanks! 👍 ../Frenck |
Co-authored-by: Simon Lamon <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
source/_integrations/schedule.markdown (4)
30-30: Improve transition between configuration sections.The transition could be clearer about what "details" can be edited.
-After creating schedule blocks, you can press a block to edit the details. +After creating schedule blocks, you can press a block to edit its start time, end time, and additional data.
49-54: Add context about the purpose of additional data attributes.Consider explaining how these attributes can be used in automations (as shown in the later example).
-Adding the following as `Additional data` will show `brightness` and `color_temp` as {% term entity %} attributes when the block is active: +Adding the following as `Additional data` will show `brightness` and `color_temp` as {% term entity %} attributes when the block is active. These attributes can then be used in automations to control your lights:
61-65: Consider moving the note about data field.The note about the
datafield would be more relevant if placed after the YAML example, where readers can see the actual usage of thedatafield.Consider moving this note block to after line 95, where the YAML example ends.
164-164: Remove trailing space.There's a trailing space at the end of this line.
-Another automation can be added to turn the lights off once the schedule is inactive: +Another automation can be added to turn the lights off once the schedule is inactive:🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
164-164: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/schedule.markdown
164-164: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
🔇 Additional comments (2)
source/_integrations/schedule.markdown (2)
15-15: LGTM! Clear and comprehensive introduction.The introduction effectively explains the Schedule integration's purpose, components, and functionality.
131-138: LGTM! Clear documentation of attributes.The attributes section effectively explains both the
next_eventand dynamic data attributes.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
source/_integrations/schedule.markdown (1)
164-180: Trailing Whitespace & Consistency Check for Automation:
The second automation example clearly outlines how to turn off the light. However, please remove any trailing whitespace (notably around line 164 as indicated by static analysis) to conform with markdown linting standards.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
164-164: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/schedule.markdown(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/schedule.markdown
164-164: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
⏰ 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 (12)
source/_integrations/schedule.markdown (12)
15-16: Introduction Clarity:
The new introductory paragraph clearly explains what the Schedule integration does and how it functions—emphasizing the activation and deactivation of time blocks. This sets a solid context for the rest of the documentation.
19-28: Configuration Layout for Basic Settings:
The configuration block using{% configuration_basic %}for the Name, Icon, and Schedule blocks is well-structured with clear descriptions. For even better readability, you might consider using a bullet list or indenting each entry consistently, but this is optional.
30-31: Editing Instructions:
The added note "After creating schedule blocks, you can press a block to edit the details." is concise and user-friendly, clearly guiding users on how to interact with the UI.
32-45: Time Fields Configuration:
This configuration block for Start, End, and Additional data is explicit and precise. The required flags and data types are well defined, which should help prevent user misconfigurations.
47-50: Additional Data Example:
The "Adding additional data" section, along with the YAML example, effectively demonstrates how the additional attributes (likebrightnessandcolor_temp) are applied when a schedule block is active. The example is clear and practical.
56-66: YAML Configuration Clarity:
The revised YAML configuration section provides a streamlined guide to manually setting up the integration via YAML. The note about thedatafield reaffirms its purpose and is a helpful addition.
68-95: Example Configuration Validation:
The comprehensive YAML example showcasing the schedule configuration is excellent. It covers multiple scenarios (different days with varying times and data) and adheres nicely to the new structure.
97-129: Configuration Schema Detail:
The configuration schema defined within the{% configuration %}block is detailed and robust. The inclusion of required fields, accurate types, and a default for thedatamapping provides clear guidance for proper setup.
131-139: Attributes Table Clarity:
The attributes table clearly outlines the key state attributes of the schedule entity. For additional clarity, you might note thatkey_1,key_2, etc., are placeholders representing the dynamic keys from the Additional data.
140-144: Automation Example Introduction:
The preliminary explanation for the automation example is succinct and effectively conveys that the schedule sensor can trigger automations such as turning lights on.
145-162: Automation Action Parameter Consistency:
In the automation example, thekelvinparameter is assigned the value from thecolor_tempattribute. Please verify that this mapping aligns with the expected input for the target light service. If the service expects a parameter namedcolor_temp, consider renaming it for consistency.
182-189: Actions Section Clarity:
The description for theschedule.reloadaction is clear and informative, effectively communicating its purpose for reloading the schedule configuration without needing a full restart.
Proposed change
Improve schedule documentation by removing doubled YAML and updating to include latest UI changes (additional data editable via UI).
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit