Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation about creating integration documentation #2541

Merged
merged 21 commits into from
Feb 20, 2025

Conversation

c0ffeeca7
Copy link
Contributor

@c0ffeeca7 c0ffeeca7 commented Jan 21, 2025

Proposed change

Add documentation about creating integration documentation

  • 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

Type of change

  • Document existing features within Home Assistant
  • Document new or changing features which there is an existing pull request elsewhere
  • Spelling or grammatical corrections, or rewording for improved clarity
  • Changes to the backend of this documentation
  • Removed stale or deprecated documentation

Additional information

  • This PR fixes or closes issue: fixes #
  • Link to relevant existing code or pull request:

Summary by CodeRabbit

  • Documentation
    • Introduced a new integration documentation guide that provides a detailed template and examples.
    • The new resource outlines best practices for formatting, inline elements, glossary terms, icons, and multimedia usage, enhancing the overall clarity and usability of the documentation.

@c0ffeeca7 c0ffeeca7 marked this pull request as ready for review January 21, 2025 14:37
Copy link
Contributor

coderabbitai bot commented Jan 21, 2025

📝 Walkthrough

Walkthrough

This 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

File Change Summary
sidebars.js Added a new entry "documenting/integration-docs-examples" in the "Documenting" category within the module exports.
docs/.../integration-docs-examples.md Created a new documentation page titled "Documentation structure and example text" with sections covering text formatting, icons, examples, and structure.

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
Loading

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?

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Generate unit testing code for this file.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai generate unit testing code for this file.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and generate unit testing code.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

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)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR. (Beta)
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai or @coderabbitai title anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between a2b3ff1 and b0b1f5e.

⛔ Files ignored due to path filters (11)
  • static/img/en/documentation/abbreviation_tooltip.png is excluded by !**/*.png
  • static/img/en/documentation/collapsible_text_block.png is excluded by !**/*.png
  • static/img/en/documentation/config_flow.png is excluded by !**/*.png
  • static/img/en/documentation/configuration_variables_ui.png is excluded by !**/*.png
  • static/img/en/documentation/configuration_variables_yaml.png is excluded by !**/*.png
  • static/img/en/documentation/glossary-term_tooltip.png is excluded by !**/*.png
  • static/img/en/documentation/image_in_step.png is excluded by !**/*.png
  • static/img/en/documentation/image_with_legend.png is excluded by !**/*.png
  • static/img/en/documentation/inline_icons.png is excluded by !**/*.png
  • static/img/en/documentation/my-links_formatting.png is excluded by !**/*.png
  • static/img/en/documentation/text_boxes.png is 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)

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between b0b1f5e and f7da6cd.

📒 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.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (2)
docs/documenting/lorem-ipsum.md (2)

238-244: Document Structure Overview

This 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 Checklist

The 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

📥 Commits

Reviewing files that changed from the base of the PR and between f7da6cd and 21ebc69.

📒 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 Declaration

The front matter is correctly defined, and the title “Documentation structure and example text” is clear and concise.


5-12: Introduction & Reference Links

The 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:

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 Section

The "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 Guidelines

The 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 Reference

The 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 Abbreviations

The explanation for handling acronyms and abbreviations—including screenshot examples and markdown usage (lines 69–80)—is clear and practical.


98-107: Inline Icons Overview

The “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 Block

The 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 Block

The 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 Boxes

The 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 Elements

The “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 Syntax

The 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 Embedding

The 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.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 21ebc69 and 44f82b8.

📒 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 the m key 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.

@MartinHjelmare MartinHjelmare merged commit 8589e39 into master Feb 20, 2025
5 checks passed
@MartinHjelmare MartinHjelmare deleted the lorem-ipsum branch February 20, 2025 21:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants