Add documentation about creating integration documentation #2541
Conversation
- showcases some documentation features such as glossary entries, My links, collapsible text, and reuse elements - shows the documentation structure - shows the example text from the integration quality scale
- example text: add titles - configuration section: add screenshots
📝 WalkthroughWalkthroughThis pull request adds a new documentation page and updates the sidebar configuration to reference it. The sidebar file is modified by adding an entry under the "Documenting" category, and a new Markdown file is introduced containing structured integration documentation with example text, guidelines, and visual illustrations. Changes
Sequence Diagram(s)sequenceDiagram
participant U as User
participant S as Sidebar
participant D as Documentation Page
U->>S: Load site with sidebar configuration
S->>U: Display sidebar with "Documenting" section
U->>S: Click on "integration-docs-examples" entry
S->>D: Route to new documentation page
D-->>U: Render documentation content
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: 0
🧹 Nitpick comments (2)
docs/documenting/lorem-ipsum.md (2)
36-36: Fix article usage in the sentence.Change "To identify a My link" to "To identify My links" or "To identify a link" for correct grammar.
-To identify a My link, in Home Assistant, open the page of interest and press the `m` key. +To identify My links, in Home Assistant, open the page of interest and press the `m` key.🧰 Tools
🪛 LanguageTool
[grammar] ~36-~36: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...(DT_PRP)
246-247: Consider consolidating duplicate Configuration entries.The navigation structure lists both "Configuration" and "Configuration options" as separate sections. Consider combining them or using more distinct names to avoid confusion.
-- [Configuration](#configuration) -- [Configuration options](#configuration-options) +- [Initial Configuration](#configuration) +- [Advanced Configuration Options](#configuration-options)🧰 Tools
🪛 LanguageTool
[duplication] ~246-~246: Possible typo: you repeated a word.
Context: ...s) - Prerequisites - Configuration - Configuration options - [Sup...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (11)
static/img/en/documentation/abbreviation_tooltip.pngis excluded by!**/*.pngstatic/img/en/documentation/collapsible_text_block.pngis excluded by!**/*.pngstatic/img/en/documentation/config_flow.pngis excluded by!**/*.pngstatic/img/en/documentation/configuration_variables_ui.pngis excluded by!**/*.pngstatic/img/en/documentation/configuration_variables_yaml.pngis excluded by!**/*.pngstatic/img/en/documentation/glossary-term_tooltip.pngis excluded by!**/*.pngstatic/img/en/documentation/image_in_step.pngis excluded by!**/*.pngstatic/img/en/documentation/image_with_legend.pngis excluded by!**/*.pngstatic/img/en/documentation/inline_icons.pngis excluded by!**/*.pngstatic/img/en/documentation/my-links_formatting.pngis excluded by!**/*.pngstatic/img/en/documentation/text_boxes.pngis excluded by!**/*.png
📒 Files selected for processing (2)
docs/documenting/lorem-ipsum.md(1 hunks)sidebars.js(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/documenting/lorem-ipsum.md
[grammar] ~36-~36: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...
(DT_PRP)
[duplication] ~246-~246: Possible typo: you repeated a word.
Context: ...s) - Prerequisites - Configuration - Configuration options - [Sup...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (4)
sidebars.js (1)
298-298: LGTM!The new documentation page is correctly added to the "Documenting" category in the sidebar navigation.
docs/documenting/lorem-ipsum.md (3)
1-8: LGTM! Clear introduction and context.The frontmatter and introduction effectively explain the purpose of the template and its relationship to existing documentation standards.
9-228: LGTM! Comprehensive coverage of documentation features.The sections effectively demonstrate various documentation features with clear examples and helpful screenshots.
🧰 Tools
🪛 LanguageTool
[grammar] ~36-~36: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...(DT_PRP)
234-513: LGTM! Well-structured documentation template.The document structure and examples provide a comprehensive template for integration documentation.
🧰 Tools
🪛 LanguageTool
[duplication] ~246-~246: Possible typo: you repeated a word.
Context: ...s) - Prerequisites - Configuration - Configuration options - [Sup...(ENGLISH_WORD_REPEAT_RULE)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/documenting/lorem-ipsum.md (1)
234-256: Consider clarifying the distinction between Configuration sections.The document structure is well-organized. However, consider adding brief descriptions to clarify the difference between "Configuration" and "Configuration options" sections to avoid confusion.
Add descriptions like this:
- Prerequisites -- Configuration -- Configuration options +- Configuration (initial setup steps) +- Configuration options (available settings and parameters) - Supported functionality🧰 Tools
🪛 LanguageTool
[duplication] ~246-~246: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/documenting/lorem-ipsum.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/documenting/lorem-ipsum.md
[grammar] ~36-~36: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...
(DT_PRP)
[duplication] ~246-~246: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...
(ENGLISH_WORD_REPEAT_RULE)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
🔇 Additional comments (4)
docs/documenting/lorem-ipsum.md (4)
1-8: LGTM! Well-structured introduction with clear purpose.The introduction effectively explains the purpose of the document and provides useful references to existing documentation standards.
9-125: LGTM! Comprehensive coverage of inline text elements.The section effectively demonstrates various text elements with clear examples and supporting screenshots. The examples are practical and cover common use cases.
🧰 Tools
🪛 LanguageTool
[grammar] ~36-~36: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...(DT_PRP)
126-169: LGTM! Clear examples of collapsible blocks and text boxes.The section effectively demonstrates the usage of collapsible blocks and text boxes with supporting screenshots.
170-233: LGTM! Comprehensive media inclusion guidelines.The section effectively covers various media types with both Markdown and HTML syntax examples.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/documenting/lorem-ipsum.md (2)
238-244: Document Structure OverviewThis section (lines 238–244) outlines the overall document structure and references the integration documentation template. One minor point: there is an inconsistency in the file extension references—the bullet list in line 9 uses “.markdown” while the structure section (line 240) refers to “_integration_docs_template.md”. Please verify that the correct, consistent extension is used across the documentation.
244-260: Basic Structure ChecklistThe list outlining the basic structure (lines 244–260) is thorough. However, the entries “Configuration” (line 250) and “Configuration options” (line 251) might be perceived as overlapping. Consider clarifying their distinct purposes or merging them if they cover similar content.
🧰 Tools
🪛 LanguageTool
[duplication] ~250-~250: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/documenting/lorem-ipsum.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/documenting/lorem-ipsum.md
[grammar] ~40-~40: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...
(DT_PRP)
[duplication] ~250-~250: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (13)
docs/documenting/lorem-ipsum.md (13)
1-3: Front Matter and Title DeclarationThe front matter is correctly defined, and the title “Documentation structure and example text” is clear and concise.
5-12: Introduction & Reference LinksThe introduction provides a clear overview of available documentation features. However, in the first bullet point (line 9) the phrasing “The integration documentation template on under…” is slightly awkward.
Consider revising it to something like:
- The integration documentation template is available under /_integrations/_integration_docs_template.markdown.
This adjustment improves readability and aligns with previous review suggestions.
- - The integration documentation template on under [/_integrations/_integration_docs_template.markdown](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/_integration_docs_template.markdown). + - The integration documentation template is available under [/_integrations/_integration_docs_template.markdown](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/_integration_docs_template.markdown).
13-41: Inline Text Elements & My Links SectionThe "Inline text elements" section—including the "My links" part with examples (lines 17–20) and the instruction (line 40)—is well documented and clear. The examples and accompanying screenshot (lines 21–26) provide useful context.
🧰 Tools
🪛 LanguageTool
[grammar] ~40-~40: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...(DT_PRP)
42-46: Formatting GuidelinesThe formatting instructions (lines 42–46) are concise and practical. The guidance on using bold and backticks for UI strings and file references adheres to best practices.
47-67: Glossary Term ReferenceThe section covering glossary term tooltips (lines 47–67) is informative and well laid out. The example code and the link to the full glossary are both helpful for readers.
69-80: Acronyms and AbbreviationsThe explanation for handling acronyms and abbreviations—including screenshot examples and markdown usage (lines 69–80)—is clear and practical.
98-107: Inline Icons OverviewThe “Inline icons” section (lines 98–107) clearly explains how to reference icons using the Iconify library. The inclusion of a screenshot further clarifies their appearance.
110-128: Inline Icons Example Code BlockThe examples for inline icons (lines 110–128) provide a comprehensive list of commonly used icons and their corresponding code. This is well executed.
130-139: Collapsible Text BlockThe section on collapsible text blocks (lines 130–139 and example code in 143–151) is well demonstrated with both a screenshot and code snippet. This makes it easy for developers to understand how to implement collapsible sections.
Also applies to: 143-151
153-172: Text BoxesThe text boxes section (lines 153–172) shows clear examples for both “note” and “important” blocks. The usage of code fences reinforces best practices for reusable documentation elements.
174-192: Reusable Text ElementsThe “Reusable text” section (lines 174–192) is straightforward. The example demonstrating how to include a configuration block is easy to follow and useful for maintaining consistency.
193-223: Images and Image SyntaxThe images section (lines 193–223) comprehensively covers both markdown and HTML approaches to adding images, complete with screenshots and captions. This ensures that users have multiple options depending on their needs.
225-236: Video EmbeddingThe video embedding section (lines 225–236) provides a clear example of how to include a YouTube video with a start time, along with a supporting screenshot. This is well implemented.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
docs/documenting/integration-docs-examples.md (4)
5-11: Clarify the Introductory Instructions
In the list item at line 9, the phrase “template on under” appears confusing. Consider revising it to “template under” or “template at” for clarity.
83-83: Minor Grammatical Correction Needed
The sentence “Here a few examples:” should be updated to “Here are a few examples:” for grammatical accuracy.
234-236: Correct Typo in Alt Text
The alt attribute in the YouTube screenshot contains a typo (“refernce”); please update it to “reference”.
238-260: Clarify the Document Structure Listing
The document structure is comprehensive; however, line 260 appears to be extraneous or incomplete. Additionally, consider reviewing the proximity of “Configuration” and “Configuration options” to ensure they are not redundant.🧰 Tools
🪛 LanguageTool
[duplication] ~250-~250: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/documenting/integration-docs-examples.md(1 hunks)sidebars.js(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- sidebars.js
🧰 Additional context used
🪛 LanguageTool
docs/documenting/integration-docs-examples.md
[grammar] ~40-~40: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...
(DT_PRP)
[duplication] ~250-~250: Possible typo: you repeated a word.
Context: ...d/unsupported devices - Prerequisites - Configuration - Configuration options - Supported functionality - Act...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (13)
docs/documenting/integration-docs-examples.md (13)
1-3: YAML Front Matter is Properly Defined
The front matter correctly specifies the document title with the proper YAML delimiters.
17-26: 'My links' Section is Clear and Informative
The explanation and example imagery correctly demonstrate how to use My links in Home Assistant.
30-38: Well-Formatted Code Block for My links Examples
The provided code block cleanly shows multiple examples and adheres to the markdown formatting standards.
40-41: Clear Shortcut Instruction
The guidance on how to identify a My link by pressing themkey is concise and easily understandable.🧰 Tools
🪛 LanguageTool
[grammar] ~40-~40: Possible typo. Did you mean “a” or “My”?
Context: ...="User profile" %} ``` To identify a My link, in Home Assistant, open the page ...(DT_PRP)
43-46: Formatting Guidelines are Clear
The instructions for using bold for UI strings and backticks for technical terms are straightforward and user-friendly.
47-66: Glossary Term Reference is Well-Described
This section clearly explains how glossary term tooltips work and includes a relevant screenshot and markdown example.
84-96: Abbreviation Examples are Well-Formatted
The code block effectively demonstrates the use of abbreviation tags with clear examples.
98-107: Inline Icons Section is Concise and Effective
The instructions and accompanying screenshot offer clear guidance on using inline icons.
130-150: Collapsible Text Block Section is Well-Illustrated
The section includes both a descriptive explanation and a practical code block example, making it easy to implement.
152-172: Text Boxes Demonstration is Clear
The examples for note and important text boxes are well-structured and effectively showcase how to use these features.
174-191: Reusable Text Section is Informative
The guidance on including reusable text blocks, along with the provided example, is clear and useful.
193-215: Images Usage is Thoroughly Covered
Both markdown and HTML methods for adding images are well-documented with clear examples and supporting screenshots.
225-237: Video Embedding Instructions are Clear
The explanation for embedding YouTube videos with a specified start time is well presented and easy to follow.
Proposed change
Add documentation about creating integration documentation
Type of change
Additional information
Summary by CodeRabbit