Update mastodon documentation #36735
Conversation
home-assistant
bot
added
has-parent
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe Mastodon integration documentation has been updated to shift its focus from notifications to direct posting actions. The changes reflect a more comprehensive approach to interacting with Mastodon, emphasizing status updates and account interactions. The documentation now provides more detailed instructions for configuring the integration, specifying required application scopes, and demonstrating new posting capabilities with enhanced parameters. Changes
Sequence DiagramsequenceDiagram
participant User
participant HomeAssistant
participant Mastodon
User->>HomeAssistant: Configure Mastodon integration
HomeAssistant->>Mastodon: Authenticate with scopes
Mastodon-->>HomeAssistant: Authorization granted
User->>HomeAssistant: Execute mastodon.post action
HomeAssistant->>Mastodon: Post status with parameters
Mastodon-->>HomeAssistant: Status posted confirmation
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 (1)
source/_integrations/mastodon.markdown (1)
62-64: Fix grammatical issues in the parameters table.There are two grammatical issues in the parameters description:
-| `content_warning` | Yes | Text will be be shown as a warning before the text of the status. If not used, no warning will be displayed. | +| `content_warning` | Yes | Text will be shown as a warning before the text of the status. If not used, no warning will be displayed. | -| `media_warning` | Yes | If an image or video is attached, `True`: will marked the media as sensitive. `False` is default. | +| `media_warning` | Yes | If an image or video is attached, `True`: will mark the media as sensitive. `False` is default. |🧰 Tools
🪛 LanguageTool
[duplication] ~62-~62: Possible typo: you repeated a word
Context: ...nt_warning` | Yes | Text will be be shown as a warning before the text of t...(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~64-~64: The modal verb ‘will’ requires the verb’s base form.
Context: ...mage or video is attached,True: will marked the media as sensitive.Falseis defa...(MD_BASEFORM)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/mastodon.markdown(3 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/mastodon.markdown
[duplication] ~62-~62: Possible typo: you repeated a word
Context: ...nt_warning` | Yes | Text will be be shown as a warning before the text of t...
(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~64-~64: The modal verb ‘will’ requires the verb’s base form.
Context: ...mage or video is attached, True: will marked the media as sensitive. False is defa...
(MD_BASEFORM)
🔇 Additional comments (5)
source/_integrations/mastodon.markdown (5)
6-6: LGTM! Integration metadata updated correctly.The addition of the Sensor category aligns with the integration's capabilities to provide account statistics.
26-26: LGTM! Required scopes correctly updated.The scopes now properly reflect all required permissions, including media upload capabilities.
47-47: LGTM! Sensor documentation is clear and complete.The section effectively describes the available sensors and their update frequency.
70-139: LGTM! Examples are comprehensive and well-structured.The examples effectively demonstrate various posting scenarios, from basic status updates to complex posts with media and content warnings. The use of the
detailstag for collapsible sections improves readability.
Line range hint
142-155: LGTM! Limitations and removal instructions are clear.The documentation effectively communicates the integration's limitations and provides proper cleanup instructions.
🧰 Tools
🪛 LanguageTool
[duplication] ~62-~62: Possible typo: you repeated a word
Context: ...nt_warning` | Yes | Text will be be shown as a warning before the text of t...(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~64-~64: The modal verb ‘will’ requires the verb’s base form.
Context: ...mage or video is attached,True: will marked the media as sensitive.Falseis defa...(MD_BASEFORM)
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
source/_integrations/mastodon.markdown (1)
Line range hint
2-2: Update description to reflect current functionalityThe description still mentions "notifications" but the integration has shifted focus to posting status updates and account statistics.
-description: Instructions on how to add Mastodon notifications to Home Assistant. +description: Instructions on how to add Mastodon status updates and account statistics to Home Assistant.
🧹 Nitpick comments (2)
source/_integrations/mastodon.markdown (2)
53-64: Add migration note for existing usersThe documentation would benefit from a migration note for users transitioning from the deprecated notify platform.
Consider adding a note before the action documentation:
{% note %} The previous `notify.mastodon` service has been deprecated in favor of the new `mastodon.post` action. If you're upgrading from a previous version, you'll need to update your automations to use the new action format shown below. {% endnote %}
74-74: Fix grammatical errorThere's a missing apostrophe in the possessive form of "account".
-Example post action that will post a status using your accounts default visibility: +Example post action that will post a status using your account's default visibility:🧰 Tools
🪛 LanguageTool
[uncategorized] ~74-~74: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...tion that will post a status using your accounts default visibility: {% raw %} ```yaml...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/mastodon.markdown(3 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/mastodon.markdown
[uncategorized] ~74-~74: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...tion that will post a status using your accounts default visibility: {% raw %} ```yaml...
(AI_HYDRA_LEO_APOSTROPHE_S_XS)
🔇 Additional comments (3)
source/_integrations/mastodon.markdown (3)
26-26: LGTM! Clear scope requirementsThe setup instructions clearly specify all required scopes for the integration's functionality.
47-47: LGTM! Clear sensor documentationThe sensor documentation clearly explains the available metrics and update frequency.
Line range hint
20-140: LGTM! Well-structured documentationThe documentation is well-organized, with clear sections covering setup, configuration, usage examples, and removal instructions. The markdown formatting follows Home Assistant documentation standards.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~74-~74: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...tion that will post a status using your accounts default visibility: {% raw %} ```yaml...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
|
@coderabbitai review |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
source/_integrations/mastodon.markdown (6)
3-6: Consider removing the Notifications category.Since the integration has moved away from notifications to focus on posting capabilities and sensors, the "Notifications" category in
ha_categorymight be misleading for users.ha_category: - - Notifications - Sensor
26-26: Enhance scope documentation clarity.Consider adding brief explanations for each required scope to help users understand why they're needed:
-Check the following scopes **read:accounts**, **write:statuses** and **write:media**. +Check the following scopes: +- **read:accounts**: Required for reading account statistics +- **write:statuses**: Required for posting status updates +- **write:media**: Required for attaching media to posts
53-55: Enhance deprecation notice with migration example.Consider adding a before/after example to help users migrate from the old notification service to the new action format.
{% note %} The previous `notify.mastodon` service has been deprecated in favor of the new `mastodon.post` action. If you're upgrading from a previous version, you'll need to update your automations to use the new action format shown below. +For example, migrate from: +```yaml +service: notify.mastodon +data: + message: "Hello from Home Assistant" +``` + +to: +```yaml +action: mastodon.post +data: + config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID + status: "Hello from Home Assistant" +``` {% endnote %}
62-68: Add parameter validation details.Consider adding validation information for the parameters:
| Data attribute | Optional | Description | |------------------------|----------|-------------| | `config_entry_id` | No | The ID of the Mastodon config entry to post to. | | `status` | No | The status text to post. | -| `visibility` | Yes | If not used, will default to account setting. `public`: post will be public, `unlisted`: post will be public but not appear on the public timeline, `private`: post will only be visible to followers, and `direct`: post will only be visible to mentioned users. | +| `visibility` | Yes | If not used, will default to account setting. Must be one of: `public` (post will be public), `unlisted` (post will be public but not appear on the public timeline), `private` (post will only be visible to followers), or `direct` (post will only be visible to mentioned users). | | `content_warning` | Yes | Text will be shown as a warning before the text of the status. If not used, no warning will be displayed. | -| `media` | Yes | Attach an image or video to the post. | +| `media` | Yes | Path to an image or video file to attach to the post. Supported formats: jpg, png, gif, mp4. | | `media_warning` | Yes | If an image or video is attached, `True` will mark the media as sensitive. `False` is default. |
74-143: Enhance examples with automation context.The examples are clear but could benefit from showing how they fit into a complete automation. Consider adding a full automation example that demonstrates real-world usage.
### Examples +{% details "Complete automation example" %} + +This example shows how to post a status update when a sensor state changes: + +{% raw %} +```yaml +automation: + - alias: "Post Temperature Alert" + description: "Post when temperature exceeds threshold" + trigger: + - platform: numeric_state + entity_id: sensor.living_room_temperature + above: 25 + action: + - action: mastodon.post + config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID + status: > + Temperature alert! Living room is at + {{ states('sensor.living_room_temperature') }}°C + visibility: private +``` +{% endraw %} + +{% enddetails %} + [existing examples follow...]
144-144: Add a troubleshooting section.Consider adding a troubleshooting section before the "Known limitations" section to help users diagnose common issues, such as:
- Authentication failures
- Media upload issues
- Rate limiting
- Common error messages and their solutions
Example structure:
## Troubleshooting ### Authentication Issues If you receive authentication errors... ### Media Upload Problems If media uploads fail... ### Rate Limiting Mastodon instances have rate limits...
Proposed change
Document the new post action and remove the deprecated notify platform.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
New Features
Documentation