Create new actions section and clarify CLI commands for NUT #38268
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe documentation for the NUT integration has been updated. A new section called Actions has been introduced, outlining that executing device actions requires credentials with Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant NI as Nut Integration
participant NS as NUT Server
User->>NI: Request device action (with credentials)
NI->>NI: Validate credentials (requires instcmds permission)
alt Credentials valid
NI->>NS: Execute parameterless command
NS-->>NI: Return command response
NI-->>User: Provide action feedback
else Credentials invalid
NI-->>User: Deny action, instruct troubleshooting
end
🪧 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)
source/_integrations/nut.markdown (2)
67-80: Clarify Credential Requirements in the New "Actions" Section
The new Actions section neatly explains that the configured username and password must possessinstcmdspermissions on the NUT server for buttons and switches to function. This clarification should help users avoid misconfiguration issues.Additionally, please consider adding blank lines before and after the "## Actions" heading to satisfy markdownlint MD022 (headings should be surrounded by blank lines). For example, if the current context does not include a blank line before line 67 or after the heading, insert one accordingly.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
67-67: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below(MD022, blanks-around-headings)
131-140: Refined "Troubleshooting" Section for Command Listing
Renaming the former "Device Actions" section to Troubleshooting and focusing on using theupscmd -lcommand clarifies that users should query the NUT server directly for available commands. This adjustment better guides users—especially those using the HACS add-on—to execute commands in the correct context.It might add further clarity to explicitly remind users that the
upscmdcommand must be executed on the NUT server (or on a system with command line access to it). If space permits, a brief note could reinforce this requirement.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/nut.markdown(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/nut.markdown
67-67: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
|
Let's hold off on changes to current until after Wed when |
|
Sounds good, I'll resume these NUT doc PRs after the release/merge. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
source/_integrations/nut.markdown (3)
278-292: Clarify “Actions” Section with Permissions NoticeThe new Actions section clearly outlines that device actions require user credentials with
instcmdspermissions, which directly addresses the documentation gaps noted in the PR objectives. This addition helps clarify that actions (i.e., parameterless NUT commands) will not be available without proper permissions. For even greater clarity, consider adding a brief note or a link explaining what is meant by “parameterless NUT commands.”
337-341: Enhance “UPS Status - human-readable version” SectionThis section neatly explains that the virtual sensor
ups.status.displaytranslates the raw UPS status into a human-readable format. To further aid users, you might consider including a practical example or visual aid that demonstrates this translation in action.
343-380: Refine Troubleshooting Section and Credential DetailsRenaming Device Actions to Troubleshooting and refocusing the content on listing available commands with
upscmd -lgreatly improves readability and better reflects the intended usage. The detailed example for the devicemy_upsis very helpful. One suggestion: since the new Actions section already emphasizes the need for credentials withinstcmdspermissions, it could be beneficial to clarify in the “User Credentials and permissions” subsection whether the credentials discussed here serve a different purpose (e.g., for executing commands via the CLI versus through Home Assistant). This additional clarification would prevent potential confusion.
Proposed change
The NUT integration's "Device Actions" section could be confusing for some users. It instructs users to use the
upscmdcommand. It is not clear, however, that the command must be run on the NUT server (and is therefore not easily accessible for those using the HACS NUT add-on).This PR create a new section for "Actions" (rather than device actions) that moves the information about the action into this section. This section will be expanded in the future to better document the actions. This new section also includes the important note about the user/password configuration (the language matches the similar note for buttons/switches that is committed to the next branch).
The remainder of the existing information with the example
upscmdcommand is moved into the start of a new "Troubleshooting" section. Additional instructions have been written to clarify where this command is executed.Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit