Improve docs readability and adjust incorrect information for switchbot integration #39701
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe documentation for the SwitchBot integration was updated to clarify device features and behaviors. New sections detail options for lock operation modes, distinctions between Circulator Fan models, expanded vacuum device states, and battery level reporting specifics. Minor formatting and wording changes were also made for clarity and consistency. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistantUI
participant SwitchBotDevice
User->>HomeAssistantUI: Selects lock operation option (e.g., Nightlatch)
HomeAssistantUI->>SwitchBotDevice: Sends command with selected option
SwitchBotDevice-->>HomeAssistantUI: Performs operation and returns status
User->>HomeAssistantUI: Checks Circulator Fan or Vacuum status
HomeAssistantUI->>SwitchBotDevice: Requests device state
SwitchBotDevice-->>HomeAssistantUI: Returns detailed state (e.g., battery, cleaning state)
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: 0
♻️ Duplicate comments (1)
source/_integrations/switchbot.markdown (1)
447-450: Apply the same heading & spacing fixes as for previous lock typesReplicate the adjustments suggested for lines 413-416 and 429-433 to keep rendering uniform across Lock / Lock Pro / Lock Ultra sections.
🧹 Nitpick comments (6)
source/_integrations/switchbot.markdown (6)
413-416: Avoid orphan “Options” heading – merge or promote to proper heading level
Options:is currently a naked paragraph label (no hashes).
For consistency with the rest of the document (e.g.#### Optionsunder Common), promote it to a heading or merge it into the preceding paragraph; otherwise screen-reader navigation and anchor linking are impaired.-Options: +#### Options
429-433: Collapse multiple blank lines to satisfy MD012There are two consecutive empty lines after the list, which violates markdown-lint rule MD012 and breaks the template’s vertical rhythm.
- - Force Nightlatch operation mode, navigate to Settings … under Integration entries - - + - Force Nightlatch operation mode, navigate to Settings … under Integration entries +
491-501: Insert blank line before subsection and refine final bullet wording
- The heading
#### Battery Circulator Fan/Circulator Fanmust be preceded by a blank line (MD022).- Bullet “get battery” is ambiguous – prefer “get battery level”.
- Ensure list is followed by a single blank line.
-Fan entities are added for Battery Circulator Fan/Circulator Fan, Air Purifier, and Air Purifier Table -#### Battery Circulator Fan/Circulator Fan +Fan entities are added for Battery Circulator Fan/Circulator Fan, Air Purifier, and Air Purifier Table + +#### Battery Circulator Fan/Circulator Fan @@ -- get battery, only applicable for Battery Circulator Fan +- get battery level (Battery Circulator Fan only)
527-531: Surround list with blank lines to silence MD032Add an empty line between
Features:and the first list item to avoid markdown-lint warnings and to stay consistent with earlier sections.-Features: -- get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details +Features: + +- get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details
547-552: Tighten grammar & punctuation in battery-level paragraphSmall copy-editing for clarity; also replace the rogue apostrophe after Lite.
-Due to firmware implementation, early models such as Lock and Lock Lite' battery level is divided into ranges instead of accurate value, <10%, shown as 10; 10%~20%, shown as 20; 20%~60%, shown as 60; ≥60%, shown as 100 +Due to firmware limitations, early models such as Lock and Lock Lite report battery level in ranges rather than precise values: +<10 % → 10 | 10–20 % → 20 | 20–60 % → 60 | ≥60 % → 100
557-559: Add blank line after heading “### Vacuum state”Headings must be separated from content by an empty line to conform with MD022.
-### Vacuum state -For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, `cleaning` and `docked` +### Vacuum state + +For robot vacuum K10+ and K10+ Pro, due to firmware limitations, only the states `cleaning` and `docked` are reported.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/switchbot.markdown(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`source/_integrations/*`: Integration documentation must use the provided template structure and section order.
source/_integrations/*: Integration documentation must use the provided template structure and section order.
source/_integrations/switchbot.markdown
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/switchbot.markdown
433-433: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
434-434: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
492-492: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
495-495: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
527-527: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
557-557: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
⏰ 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
| @@ -410,6 +410,10 @@ Features: | |||
| - calibration state | |||
| - get battery level | |||
|
|
|||
| Options: | |||
|
|
|||
| - Force Nightlatch operation mode, navigate to Settings > Devices & services > Configured > SwitchBot Bluetooth and tap CONFIGURE under Integration entries | |||
There was a problem hiding this comment.
what do you mean by "Force nightlatch operation mode"? Does it mean "To enable nightlatch operation mode"?
What is Nightlatch operation mode?
There was a problem hiding this comment.
what do you mean by "Force nightlatch operation mode"? Does it mean "To enable nightlatch operation mode"? What is Nightlatch operation mode?
You are right, i have changed the description
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
source/_integrations/switchbot.markdown (4)
413-416: Consider deduplicating & tightening the repeated “nightlatch operation mode” bulletThe three option blocks are identical, which is fine, but it is easy for them to diverge in future edits and forces readers to scroll.
A single generic paragraph right after the “Locks” heading (or a shared subsection such as##### Night-latch mode) would make maintenance easier and avoid copy-paste drift.Also applies to: 429-432, 447-450
433-434: Remove the extra blank lines to satisfy MD012Two consecutive empty lines are flagged by the linter. One is enough.
- -
526-528: Add the missing blank line before the list (MD032) and tighten wordingFeatures: + - get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details
557-559: Heading spacing (MD022) and phrasingAdd a blank line after the heading and adjust the sentence for number agreement.
-### Vacuum state -For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, `cleaning` and `docked` +### Vacuum state + +Due to firmware limitations, the K10+ and K10+ Pro robots currently expose only two states: `cleaning` and `docked`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/switchbot.markdown(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`source/_integrations/*`: Integration documentation must use the provided template structure and section order.
source/_integrations/*: Integration documentation must use the provided template structure and section order.
📄 Source: CodeRabbit Inference Engine (.github/copilot-instructions.md)
List of files the instruction was applied to:
source/_integrations/switchbot.markdown
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/switchbot.markdown
433-433: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
434-434: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
492-492: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
495-495: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
527-527: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
557-557: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
source/_integrations/switchbot.markdown (4)
429-434: Remove extra blank line after the bulletMarkdown-lint (MD012) flags two consecutive blank lines here. Keep a single blank line to avoid unnecessary vertical whitespace.
- - To enable nightlatch operation mode, navigate to Settings > Devices & services > Configured > SwitchBot Bluetooth and tap CONFIGURE under Integration entries - - + - To enable nightlatch operation mode, navigate to Settings > Devices & services > Configured > SwitchBot Bluetooth and tap CONFIGURE under Integration entries +
491-501: Missing blank line before the list (MD032)Add a blank line between
Features:and the first list item so the list renders correctly.-Features: -- turn on +Features: + + - turn on
527-531: Same list-spacing issue under VacuumsInsert a blank line after
Features:for consistency and to silence MD032.-Features: -- get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details +Features: + + - get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to the Known limitations section for more details
563-565: Heading needs a trailing blank line (MD022)Add one blank line after the
### Vacuum stateheading.-### Vacuum state -For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, `cleaning` and `docked` +### Vacuum state + +For robot vacuum K10+ and K10+ Pro, due to firmware limitations, only the `cleaning` and `docked` states are reported.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/switchbot.markdown(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`source/_integrations/*`: Integration documentation must use the provided template structure and section order.
source/_integrations/*: Integration documentation must use the provided template structure and section order.
📄 Source: CodeRabbit Inference Engine (.github/copilot-instructions.md)
List of files the instruction was applied to:
source/_integrations/switchbot.markdown
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/switchbot.markdown
433-433: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
434-434: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
496-496: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
528-528: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
563-563: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
⏰ 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/_integrations/switchbot.markdown (3)
413-416: Lock – Options section looks goodWording and spacing comply with the template; no issues spotted.
447-450: Lock Ultra – Options section looks goodNo lint or clarity issues observed.
548-556: Battery level section ✔️Formatting, grammar, and the bullet list are clear and follow previous feedback.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
source/_integrations/switchbot.markdown (6)
413-418: Drop the colon to keep headings consistent with the rest of the docEvery other
#### Optionsheading in this document (and in the template) omits the trailing colon.
Removing it avoids visual noise and keeps the markdown style uniform.-Options: +Options
431-438: Fix heading + excess blank lines (MD022/MD012)
- Same heading-colon issue as above.
- Two consecutive blank lines after the ordered list violate MD012.
-Options: +Options …steps… - - + <!-- keep a single terminating blank line -->
451-456: Consistent heading & spacing for “Lock Ultra” sectionReplicate the corrections applied to the previous two blocks:
-Options: +OptionsNo extra blank lines are needed after the ordered list.
497-508: Grammar + markdown-lint: add blank line before list & clarify sentence
- MD032 – a blank line is required between “Features:” and the list.
- The introductory sentence reads awkwardly; split the model names.
-Fan entities are added for Battery Circulator Fan/Circulator Fan, Air Purifier, and Air Purifier Table +Fan entities are added for Battery Circulator Fan, Circulator Fan, Air Purifier, and Air Purifier Table #### Battery Circulator Fan/Circulator Fan … -Features: +Features: <!-- blank line above satisfies MD032 -->
533-538: List spacing + wording improvements
- MD032 – needs a blank line after “Features:”.
- Use “battery level” to match wording elsewhere.
- “get states” → “retrieve state” (singular is used in other sections).
-Features: +Features: -- get states, including `cleaning`, `docked`, `idle`, `paused`, `returning`, and `error`; refer to Known limitations for more details +- retrieve state (values: `cleaning`, `docked`, `idle`, `paused`, `returning`, `error` – see Known limitations) - start - return to base -- get battery +- get battery level
569-572: Grammar tweak for subject-verb agreement-For robot vacuum K10+ and K10+ Pro, due to firmware implementation, it only returns these states, `cleaning` and `docked` +Due to firmware limitations, the K10+ and K10+ Pro robot vacuums only return two states: `cleaning` and `docked`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_integrations/switchbot.markdown(6 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`source/_integrations/*`: Integration documentation must use the provided template structure and section order.
source/_integrations/*: Integration documentation must use the provided template structure and section order.
📄 Source: CodeRabbit Inference Engine (.github/copilot-instructions.md)
List of files the instruction was applied to:
source/_integrations/switchbot.markdown
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/switchbot.markdown
437-437: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
438-438: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
502-502: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
534-534: Lists should be surrounded by blank lines
null
(MD032, blanks-around-lists)
⏰ 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
Proposed change
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit