Create Claude instructions for ESPHome docs #5641
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Rate limit exceeded@jesserockz has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 16 minutes and 35 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds a new ESPHome documentation guidance file at Changes
Sequence Diagram(s)(omitted — changes are documentation-only and do not modify control flow) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
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. Comment |
![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 (1)
.claude/instructions.md (1)
94-94: Capitalize "Markdown" as a proper noun.On Line 94, "markdown syntax" should be "Markdown syntax" per standard style conventions. Apply this diff:
-Standard markdown syntax: +Standard Markdown syntax:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.claude/instructions.md(1 hunks)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 5348
File: themes/esphome-theme/layouts/index.componentsjson:29-31
Timestamp: 2025-09-11T00:57:49.493Z
Learning: In the esphome-docs repository, the components.json generation should flatten component paths to exclude parent directories (e.g., "components/fileName" not "components/parentDir/fileName") to match how the source code repository is structured.
📚 Learning: 2025-05-12T00:02:50.869Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:08:25.575Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-09-11T00:57:49.493Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 5348
File: themes/esphome-theme/layouts/index.componentsjson:29-31
Timestamp: 2025-09-11T00:57:49.493Z
Learning: In the esphome-docs repository, the components.json generation should flatten component paths to exclude parent directories (e.g., "components/fileName" not "components/parentDir/fileName") to match how the source code repository is structured.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:12:25.536Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 4874
File: guides/yaml.rst:324-324
Timestamp: 2025-05-05T05:12:25.536Z
Learning: When reviewing Sphinx documentation in the ESPHome project, leave the leading slashes in doc references (`:doc:/path`) intact, as they provide absolute paths which are required when the source document is not at the root of the tree.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-01T03:29:47.922Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-28T05:38:05.301Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4897
File: components/json.rst:130-131
Timestamp: 2025-05-28T05:38:05.301Z
Learning: In ESPHome documentation, the correct Sphinx role for API references is `:apiref:` (e.g., `:apiref:`http_request/http_request.h``), not `:api-ref:` or roles with spaces like `:http_request api ref:`.
Applied to files:
.claude/instructions.md
🪛 LanguageTool
.claude/instructions.md
[style] ~22-~22: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...ion** like GPIOXX instead of specific pin numbers - Example: Use GPIO16 rather than `D0...
(PIN_NUMBER)
[style] ~62-~62: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...s, variable names, short code snippets, pin numbers #### Code Blocks - Use triple backtick...
(PIN_NUMBER)
[uncategorized] ~94-~94: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...### Links #### External Links Standard markdown syntax: ```markdown [ESP32 Datasheet](h...
(MARKDOWN_NNP)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Agent
- GitHub Check: Build
🔇 Additional comments (4)
.claude/instructions.md (4)
99-105: Excellent alignment with ESPHome documentation conventions.The relative path guidance for internal documentation links (using leading
/) correctly reflects the absolute path requirement in this codebase when source documents are not at the root level. Based on learnings
152-157: Branch strategy guidance is well-aligned with repository conventions.The distinction between
current(fixes/corrections) andnext(new features/docs) correctly matches the automated branch assignment behavior in this repository. Based on learnings
1-264: Comprehensive and well-structured documentation guidance.The file provides excellent coverage of ESPHome documentation standards including frontmatter requirements, heading hierarchy, code formatting, linking conventions, visual elements, and git workflows. The distinction between minimal (good) vs. excessive (bad) configuration examples on lines 225-248 effectively communicates the philosophy of clarity over completeness. The pre-submission checklist (lines 187-193) provides practical validation steps.
120-130: Consider adding @esphomebot image generation instructions.The PR objectives reference a "New Component Images" section explaining how to use the
@esphomebot generate image COMPONENT_NAMEcommand to generate standardized SVG component images. This section does not appear in the current instructions file. If this is intended to be part of the documentation guidance (rather than handled separately in the PR process), consider adding a section covering:
- How to invoke
@esphomebot generate image COMPONENT_NAME- Where to extract and place the generated SVG in
/images/- How to reference it in
/components/index.rstShould this section be included in these instructions, or is it handled through a separate process document?
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation instructions for Claude AI to assist with ESPHome documentation contributions. The file provides detailed guidelines covering style, formatting, markdown syntax, Git workflow, and common patterns.
Key additions:
- Documentation style guidelines (language, formatting, tone)
- Markdown syntax standards and code formatting rules
- Git workflow and branching strategy for Claude-generated contributions
- Common patterns for component documentation pages
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
.claude/instructions.md (2)
119-131: Update image directory path and addimgshortcode guidance.Per past review feedback, the image directory path is incorrect and the guidance is incomplete:
- Images should be placed in
/static/images/(not/images/)—the/static/prefix is required per project structure- The Hugo
imgshortcode should be documented as the preferred method, as it provides additional features (captions, width control, CSS classes) already used in existing documentationApply this diff:
#### Images - **Optimize all images** before adding (use TinyPNG/TinyJPG) - **Maximum size**: ~1000x800 pixels - Place images in `/images/` directory - Reference with: `` + **Optimize all images** before adding (use TinyPNG/TinyJPG) + **Maximum size**: ~1000x800 pixels + **Preferred:** Use the Hugo `img` shortcode to reference images, as it supports captions, width control, and CSS classes: + ```markdown + {{< img src="/images/component-name.png" alt="Alt text" >}} + ``` + For simple images without extra features, you may use standard Markdown: + ```markdown +  + ``` + **Note:** All image paths use `/images/` in frontmatter but should be stored in `/static/images/` directory #### Component Thumbnails - **Aspect ratio**: 8:10 (portrait orientation) - **Format**: SVG (heavily compressed) or JPG (300x300px) - **Location**: `/images/` directory + **Location**: `/static/images/` directory
191-191: Replace≤with<=for terminal compatibility.The checklist symbol
≤may not render correctly in all terminals and editors. Use the ASCII-compatible<=instead.- [ ] Confirm line length is ≤120 characters + [ ] Confirm line length is <=120 characters
🧹 Nitpick comments (2)
.claude/instructions.md (2)
22-22: [Optional] Minor wording refinement.The static analysis tool flags "pin numbers" as slightly redundant (LanguageTool: "N stands for number"). Consider using "pins" for slightly more concise phrasing:
Line 22: - **ALWAYS use the literal string `GPIOXX`** in documentation examples - The `XX` is literal - do NOT replace with actual numbers like `GPIO16` - **Exception**: Only use specific pin numbers when documenting hardware with fixed pins + **ALWAYS use the literal string `GPIOXX`** in documentation examples + The `XX` is literal - do NOT replace with actual pins like `GPIO16` + **Exception**: Only use specific pins when documenting hardware with fixed pins Line 62: - Use for: component names, variable names, short code snippets, pin numbers + Use for: component names, variable names, short code snippets, pinsThis is purely stylistic and the current phrasing is acceptable.
Also applies to: 62-62
94-94: Capitalize "Markdown" as proper noun.Per static analysis, "markdown" should be capitalized as "Markdown" when referring to the markup language.
- Standard markdown syntax: + Standard Markdown syntax:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.claude/instructions.md(1 hunks)
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
📚 Learning: 2025-05-12T00:02:50.869Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:08:25.575Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-09-11T00:57:49.493Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 5348
File: themes/esphome-theme/layouts/index.componentsjson:29-31
Timestamp: 2025-09-11T00:57:49.493Z
Learning: In the esphome-docs repository, the components.json generation should flatten component paths to exclude parent directories (e.g., "components/fileName" not "components/parentDir/fileName") to match how the source code repository is structured.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:12:25.536Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 4874
File: guides/yaml.rst:324-324
Timestamp: 2025-05-05T05:12:25.536Z
Learning: When reviewing Sphinx documentation in the ESPHome project, leave the leading slashes in doc references (`:doc:/path`) intact, as they provide absolute paths which are required when the source document is not at the root of the tree.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-01T03:29:47.922Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Applied to files:
.claude/instructions.md
🪛 LanguageTool
.claude/instructions.md
[style] ~22-~22: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...ion** like GPIOXX instead of specific pin numbers - Example: Use GPIO16 rather than `D0...
(PIN_NUMBER)
[style] ~62-~62: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...s, variable names, short code snippets, pin numbers #### Code Blocks - Use triple backtick...
(PIN_NUMBER)
[uncategorized] ~94-~94: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...### Links #### External Links Standard markdown syntax: ```markdown [ESP32 Datasheet](h...
(MARKDOWN_NNP)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
🔇 Additional comments (2)
.claude/instructions.md (2)
100-106: Internal documentation links are correctly formatted.The use of relative paths with leading slashes (e.g.,
/components/wifi) provides the required absolute paths for the ESPHome documentation structure. This aligns with project conventions.
153-175: Git workflow guidance is aligned with project conventions.The branch strategy (lines 156-157) correctly directs documentation fixes to
currentand new features tonext, matching established project conventions. This PR appropriately targetscurrentfor documentation instructions.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
.claude/instructions.md (2)
124-125: Update image directory path to match project structure.Per the project structure established in past reviews, images should be placed in
/static/images/, not/images/. Additionally, the Hugoimgshortcode should be documented as the preferred method for referencing images, as it supports captions, width control, and CSS classes.Apply this diff to correct the image documentation:
#### Images - - **Optimize all images** before adding (use TinyPNG/TinyJPG) + - **Optimize all images** before adding (use TinyPNG or TinyJPG) - **Maximum size**: ~1000x800 pixels - - Place images in `/images/` directory - - Reference with: `` + - Place images in `/static/images/` directory (the `/static/` prefix is required for the project structure) + - **Preferred:** Use the Hugo `img` shortcode to reference images, as it supports captions, width control, and CSS classes: + ```markdown + {{< img src="/images/component-name.png" alt="Alt text" >}} + ``` + - For simple images without extra features, you may use standard Markdown: + ```markdown +  + ``` #### Component Thumbnails - **Aspect ratio**: 8:10 (portrait orientation) - **Format**: SVG (heavily compressed) or JPG (300x300px) - - **Location**: `/images/` directory + - **Location**: `/static/images/` directoryAlso applies to: 130-130
188-188: Replace non-ASCII character for terminal compatibility.The
≤symbol may not render correctly in all terminals and text editors. Use<=instead for better cross-platform compatibility.Apply this diff:
- - [ ] Confirm line length is ≤120 characters + - [ ] Confirm line length is <=120 characters
🧹 Nitpick comments (1)
.claude/instructions.md (1)
95-95: Capitalize "Markdown" as a proper noun."Markdown" is a proper noun and should be capitalized.
Apply this diff:
- #### External Links - Standard markdown syntax: + #### External Links + Standard Markdown syntax:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.claude/instructions.md(1 hunks)
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
📚 Learning: 2025-05-05T05:08:25.575Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: In ESPHome documentation, leading slashes in doc references are necessary when the source document is not at the root of the tree, as absolute paths to referenced documents are required in this context.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-12T00:02:50.869Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4901
File: changelog/2025.4.0.rst:124-126
Timestamp: 2025-05-12T00:02:50.869Z
Learning: In the ESPHome changelog structure, the "All changes" section should have the `:open:` attribute to be expanded by default, but the "Dependency Changes" section should NOT have this attribute as it should remain collapsed by default.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-09-11T00:57:49.493Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 5348
File: themes/esphome-theme/layouts/index.componentsjson:29-31
Timestamp: 2025-09-11T00:57:49.493Z
Learning: In the esphome-docs repository, the components.json generation should flatten component paths to exclude parent directories (e.g., "components/fileName" not "components/parentDir/fileName") to match how the source code repository is structured.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:12:25.536Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 4874
File: guides/yaml.rst:324-324
Timestamp: 2025-05-05T05:12:25.536Z
Learning: When reviewing Sphinx documentation in the ESPHome project, leave the leading slashes in doc references (`:doc:/path`) intact, as they provide absolute paths which are required when the source document is not at the root of the tree.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-01T03:29:47.922Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-28T05:38:05.301Z
Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4897
File: components/json.rst:130-131
Timestamp: 2025-05-28T05:38:05.301Z
Learning: In ESPHome documentation, the correct Sphinx role for API references is `:apiref:` (e.g., `:apiref:`http_request/http_request.h``), not `:api-ref:` or roles with spaces like `:http_request api ref:`.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-05-05T05:08:25.575Z
Learnt from: clydebarrow
Repo: esphome/esphome-docs PR: 0
File: :0-0
Timestamp: 2025-05-05T05:08:25.575Z
Learning: For code blocks within YAML documents in ESPHome, maintain YAML format even when the content uses JSON-style syntax, since YAML is a superset of JSON, but not all YAML is valid JSON.
Applied to files:
.claude/instructions.md
📚 Learning: 2025-08-24T00:13:13.459Z
Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
Applied to files:
.claude/instructions.md
🪛 LanguageTool
.claude/instructions.md
[style] ~24-~24: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...O16` - Exception: Only use specific pin numbers when documenting hardware with fixed pi...
(PIN_NUMBER)
[style] ~63-~63: This phrase is redundant (‘N’ stands for ‘number’). Consider using “pins”.
Context: ...s, variable names, short code snippets, pin numbers #### Code Blocks - Use triple backtick...
(PIN_NUMBER)
[uncategorized] ~95-~95: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...### Links #### External Links Standard markdown syntax: ```markdown [ESP32 Datasheet](h...
(MARKDOWN_NNP)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build
jesserockz
deleted the
claude/esphome-docs-instructions-01NRNSp46nSEDS1W3f35iC3n
branch
Description:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: