Add docs for as_function and apply #38730
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe documentation for Home Assistant templating was enhanced to include the "Expression Statement" Jinja extension ( Changes
Sequence Diagram(s)sequenceDiagram
participant Template as Jinja Template
participant Macro as Macro with returns argument
participant as_function as as_function Filter
participant apply as apply Function
participant User as Template User
User->>Template: Define macro with returns argument
Template->>Macro: Call macro with returns=callback
Macro->>returns: Invoke returns with value (e.g., dict, number)
User->>as_function: Convert macro to callable function
as_function->>Macro: Provide returns callback
Macro-->>as_function: Return native value via returns
User->>apply: Use apply to invoke macro/function with parameters
apply->>Macro: Call macro/function with arguments
Macro-->>apply: Return result (native type)
apply-->>User: Provide result in template context
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🔇 Additional comments (4)
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: 2
🧹 Nitpick comments (1)
source/_docs/configuration/templating.markdown (1)
106-114: Macro example is clear and functional
Themacro_is_switchsnippet correctly demonstrates usingdo returns(...)and converting to a callable viaas_function.
Consider switching the code-fence language fromtexttojinjafor syntax highlighting.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(3 hunks)
⏰ 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 (3)
source/_docs/configuration/templating.markdown (3)
67-67: Addition of Expression Statement extension looks good
Including thedo(Expression Statement) extension is correct for enabling side-effect statements in macros.
102-104: Great explanation of non-string macro returns
The description of passing areturnsargument and converting a macro withas_functionis accurate and clear.
118-119: Good summary of exporting utility functions
The closing remark effectively reinforces that you can return native types instead of only rendering strings.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
source/_docs/configuration/templating.markdown (2)
102-120: Remove duplicatedas_functionexample
This snippet under Reusing templates duplicates the detailed documentation introduced later in the "Working with macros" section. To avoid confusion, consolidate into a single location (preferably the dedicated "Working with macros" section) as suggested in a previous review.
100-101:⚠️ Potential issueFix raw block closing tag
The current closing tag{$ endraw }}is invalid and will break the build. It should be:- {$ endraw }} + {% endraw %}
🧹 Nitpick comments (2)
source/_docs/configuration/templating.markdown (2)
67-67: Consistent Jinja extension version links
You’ve added the Expression Statement extension (do), which is great. To keep link styles consistent, consider using the same version path for both extensions. For example, change the Loop Controls link to/en/latest/extensions/#loop-controlsor update the Expression Statement link to/en/3.0.x/extensions/#expression-statement.
1378-1396: Documentapplyandas_functionfilters
This new section clearly explains theapplyandas_functionfeatures. Consider adding a minimal code block example withjinjasyntax highlighting for theapplyuse case, for instance:{{ [1,2,3] | map('apply', double) | list }}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_docs/configuration/templating.markdown(4 hunks)
⏰ 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 (1)
source/_docs/configuration/templating.markdown (1)
83-83: Explicitjinjasyntax highlighting
Adding thejinjalanguage tag to the code block improves readability in rendered docs.
Proposed change
Adds documentation for
as_functionandapplyas described here: home-assistant/core#142033 home-assistant/core#144227Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
Summary by CodeRabbit
applyandas_functionfunctions, demonstrating advanced template processing techniques.