Add paperless_ngx docs #39103
Add paperless_ngx docs #39103
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughA new documentation file for the Paperless-ngx integration has been added. This file provides setup instructions, configuration details, and sensor information for connecting Paperless-ngx to Home Assistant, including authentication requirements and removal procedures. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant HomeAssistant
participant PaperlessNGX
User->>PaperlessNGX: Create API access token
User->>HomeAssistant: Configure Paperless-ngx integration (host, token)
HomeAssistant->>PaperlessNGX: Authenticate using API token
PaperlessNGX-->>HomeAssistant: Return status and metrics
HomeAssistant-->>User: Display Paperless-ngx sensors and status
Note ⚡️ AI Code Reviews for VS Code, Cursor, WindsurfCodeRabbit now has a plugin for VS Code, Cursor and Windsurf. This brings AI code reviews directly in the code editor. Each commit is reviewed immediately, finding bugs before the PR is raised. Seamless context handoff to your AI code agent ensures that you can easily incorporate review feedback. Note ⚡️ Faster reviews with cachingCodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 30th. To opt out, configure 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: 1
🧹 Nitpick comments (2)
source/_integrations/paperless_ngx.markdown (2)
2-3: Fix verb usage in descriptionThe description uses "setup" as a verb; it should be "set up" for correct usage.
Apply this diff:--- description: Instructions on how to setup the Paperless-ngx integration +++ description: Instructions on how to set up the Paperless-ngx integration
36-38: Remove extra blank lineThere are multiple consecutive blank lines before the config flow include, which may trigger markdownlint errors (MD012). Reduce them to a single blank line.
Apply this diff:- - +🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/paperless_ngx.markdown
[uncategorized] ~52-~52: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ngx: - Number of documents - Number of document with inbox tags - Status of the databas...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ 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 (5)
source/_integrations/paperless_ngx.markdown (5)
1-17: Frontmatter is well-structuredThe YAML frontmatter follows Home Assistant guidelines and correctly defines metadata such as
ha_release,ha_category, andha_codeowners.
21-26: Prerequisites section is clearThe permissions requirements for read and admin access are well-documented and adhere to standards.
38-38: Config flow include is correctThe
{% include integrations/config_flow.md %}directive properly injects the integration setup instructions.
40-45: Basic configuration block is properly definedThe
configuration_basicblock clearly specifies the requiredhostandaccess tokenparameters.
61-65: Removal instructions are sufficientThe removal section follows the standard pattern, and the
{% include integrations/remove_device_service.md %}is correctly referenced.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
source/_integrations/paperless_ngx.markdown (1)
51-59: Standardize sensor list items
The sensor bullet list has inconsistent phrasing and grammatical issues.Apply this diff to harmonize and pluralize items:
- - Number of documents - - Number of document with inbox tags - - Status of the database with errors - - Status of Redis with errors - - Status of Celery - - Status of classifier with errors - - Status of index with errors - - Storage Total - - Storage Available + - Number of documents + - Number of documents with inbox tags + - Database status + - Redis status + - Celery status + - Classifier status + - Index status + - Total storage + - Available storage🧰 Tools
🪛 LanguageTool
[uncategorized] ~52-~52: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ngx: - Number of documents - Number of document with inbox tags - Status of the databas...(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
🧹 Nitpick comments (2)
source/_integrations/paperless_ngx.markdown (2)
3-3: Fix verb usage in description
The phrase "how to setup" uses the noun "setup" instead of the verb "set up." Please update for grammatical accuracy.- description: Instructions on how to setup the Paperless-ngx integration + description: Instructions on how to set up the Paperless-ngx integration
36-37: Remove extra blank lines
Two consecutive blank lines appear after{% enddetails %}, violating markdown style (MD012). Consolidate to a single blank line.@@ -35,3 +35,2 @@ {% enddetails %} - - +🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/paperless_ngx.markdown
[uncategorized] ~52-~52: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ...ngx: - Number of documents - Number of document with inbox tags - Status of the databas...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ 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 (8)
source/_integrations/paperless_ngx.markdown (8)
1-2: Frontmatter metadata is well-structured
The YAML frontmatter fields correctly define the integration metadata.
4-17: Frontmatter metadata after description looks good
Fields such asha_release,ha_domain, and related links are correctly specified.
19-20: Introduction is clear and concise
The overview correctly describes the integration’s purpose and usage.
21-26: Prerequisites section is informative
Requirements for read and administrator permissions are clearly stated.
27-35: Access token creation steps are well-written
The step-by-step instructions under the details block are clear and actionable.
38-45: Configuration flow include and basic config snippet
Inclusion ofconfig_flow.mdand use of theconfiguration_basicmacro align with Home Assistant documentation standards.
47-49: Sensors header is properly defined
Section title and introductory sentence follow Home Assistant conventions.
61-65: Removing integration instructions are correct
This section follows the standard Home Assistant removal procedure without extra steps.
|
I'm drafting this PR, as changes are needed. Please undraft it, once the changes have been implemented and the PR is ready for review again. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
source/_integrations/paperless_ngx.markdown (2)
37-38: Remove extra blank lines to satisfy MD012
There are two consecutive blank lines before theconfig_flowinclude. Reduce to a single blank line to adhere to markdownlint rules.Apply this diff:
{% enddetails %} - - {% include integrations/config_flow.md %} +🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
56-57: Remove extra blank lines to satisfy MD012
There are two consecutive blank lines after the sensors table. Please leave only one blank line before the next section header.Apply this diff:
| **Firmware** | Displays the installed and latest version of the Paperless-ngx instance. | - - ## Removing the integration +
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
55-55: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
source/_integrations/paperless_ngx.markdown (3)
35-38: Remove extra blank lines for consistency
The static analysis tool flagged multiple consecutive blank lines between the end of the details block and the config flow include (MD012). Consolidate to a single blank line to maintain readability.-{% enddetails %} - - +{% enddetails %} {% include integrations/config_flow.md %}🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
30-33: Clarify token generation step
Simplify the wording in step 4 to remove directional details and make the instruction more concise.-4. Under **API Auth Token**, select the right **Refresh** button next to the textbox to generate a new token. Confirm with **yes**. +4. Under **API Auth Token**, click the **Refresh** button to generate a new token, then confirm.
53-57: Consolidate blank lines around the sensors table
There are two blank lines between the table and the “Removing the integration” section. Reduce to a single blank line for a cleaner layout.| **Firmware** | Displays the installed and latest version of the Paperless-ngx instance. | - - ## Removing the integration🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
55-55: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
55-55: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ 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
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
source/_integrations/paperless_ngx.markdown (1)
40-45: Use lowercase snake_case for configuration keys
Configuration keys in Home Assistant docs should be lowercase and snake_case to match integration parameters.{% configuration_basic %} -Host: +host: description: "The host to connect to" -API key: - description: "The API key for the Paperless-ngx user." +access_token: + description: "The API key for the Paperless-ngx user." {% endconfiguration_basic %}
🧹 Nitpick comments (3)
source/_integrations/paperless_ngx.markdown (3)
36-37: Remove extra blank lines for markdown style consistency
There are two consecutive blank lines between the end of the details block and the include. Reduce to a single blank line to satisfy MD012 (no-multiple-blanks).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
55-55: Add missing period to sensor description
The description for Tags total is missing a trailing period.-| **Tags total** | Indicates the total number of defined tags | +| **Tags total** | Indicates the total number of defined tags. |
60-61: Remove extra blank lines before the next section
Lines 60–61 are two blank lines preceding the “## Removing the integration” heading. Collapse to a single blank line to comply with markdownlint’s MD012 rule.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
60-60: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
61-61: Multiple consecutive blank lines
Expected: 1; Actual: 3(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
60-60: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
61-61: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
⏰ 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 (1)
source/_integrations/paperless_ngx.markdown (1)
7-7: Verifyha_iot_classvalue against Home Assistant standards
The valueLocal Pullmay not match the officially supported IoT class identifiers (e.g.,local_poll,local_push). Please confirm and adjust to a valid, lowercase snake_case identifier if needed.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
source/_integrations/paperless_ngx.markdown (1)
40-45: 🛠️ Refactor suggestionStandardize configuration keys to lowercase snake_case
Configuration keys must match the integration’s parameters and follow Home Assistant’s snake_case convention. RenameHost→hostandAPI key→access_token, and update the description accordingly.{% configuration_basic %} -Host: - description: "The host to connect to" -API key: - description: "The API key for the Paperless-ngx user." +host: + description: "The host to connect to" +access_token: + description: "The access token for the Paperless-ngx user." {% endconfiguration_basic %}
🧹 Nitpick comments (3)
source/_integrations/paperless_ngx.markdown (3)
36-38: Remove extra blank lines between the details block and config flow include
There are two consecutive blank lines before the{% include integrations/config_flow.md %}directive. Collapse to a single blank line to satisfy markdownlint’s MD012 rule and improve readability.-{% enddetails %} - - -{% include integrations/config_flow.md %} +{% enddetails %} + +{% include integrations/config_flow.md %}🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
53-58: Normalize sensor names’ capitalization & add missing punctuation
Table entries should use consistent Title Case for sensor names, and descriptions should end with a period.-| **Document types** | Indicates the total number of defined document types. | +| **Document Types** | Indicates the total number of defined document types. | -| **Documents in inbox** | Indicates the number of documents currently in the inbox. | +| **Documents in Inbox** | Indicates the number of documents currently in the inbox. | -| **Tags** | Indicates the total number of defined tags | +| **Tags** | Indicates the total number of defined tags. |
59-62: Remove extra blank line before the “Removing the integration” section
There are two blank lines separating the sensors table and the next header. Collapse to a single blank line to satisfy markdownlint’s MD012 rule.-| **Total documents** | Indicates the total number of documents stored. | - -## Removing the integration +| **Total documents** | Indicates the total number of documents stored. | +## Removing the integration🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
60-60: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
37-37: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
60-60: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ 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
| ha_release: 2025.7 | ||
| ha_category: | ||
| - Sensor | ||
| ha_iot_class: Local Pull |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Use the correct IoT class constant
Home Assistant IoT class values must be lowercase snake_case. Replace the human-readable "Local Pull" with the appropriate constant local_poll to ensure consistency with other integrations and proper rendering.
- ha_iot_class: Local Pull
+ ha_iot_class: local_poll📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ha_iot_class: Local Pull | |
| ha_iot_class: local_poll |
🤖 Prompt for AI Agents
In source/_integrations/paperless_ngx.markdown at line 7, the IoT class value
"Local Pull" is incorrectly capitalized and spaced. Replace this human-readable
string with the lowercase snake_case constant "local_poll" to conform to Home
Assistant's IoT class naming conventions and maintain consistency across
integrations.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
source/_integrations/paperless_ngx.markdown (2)
39-44: Standardize and correct configuration keys
Home Assistant configuration keys should be lowercase snake_case and match the integration parameters. RenameHosttohostandAPI keytoaccess_token, and update the description accordingly.
Apply this diff:{% configuration_basic %} -Host: - description: "The host to connect to" -API key: - description: "The API key for the Paperless-ngx user." +host: + description: "The host to connect to" +access_token: + description: "The API auth token for the Paperless-ngx user." {% endconfiguration_basic %}
7-7: 🛠️ Refactor suggestionUse correct IoT class constant
Theha_iot_classvalue should use the lowercase snake_case constantlocal_pollinstead of the human-readable"Local Polling"to adhere to Home Assistant conventions.
Apply this diff:-ha_iot_class: Local Polling +ha_iot_class: local_poll
🧹 Nitpick comments (2)
source/_integrations/paperless_ngx.markdown (2)
55-55: Ensure consistent punctuation in sensor table
Add a missing period at the end of the description for the Tags sensor to match the other entries.-| **Tags** | Indicates the total number of defined tags +| **Tags** | Indicates the total number of defined tags.
59-60: Remove extra blank line
There are multiple consecutive blank lines before the removal section. Reduce to a single blank line to satisfy markdown lint rules (MD012).- - +🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
59-59: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
59-59: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
⏰ 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
|
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: 1
♻️ Duplicate comments (3)
source/_integrations/paperless_ngx.markdown (3)
7-7: Use the correct IoT class constant.Home Assistant IoT class values should be lowercase snake_case. Replace:
- ha_iot_class: Local Polling + ha_iot_class: local_poll
37-42: Standardize configuration key names to snake_case.Configuration keys must be lowercase snake_case to match the integration’s parameters. Update this block:
{% configuration_basic %} -URL: - description: "URL to connect to the Paperless-ngx instance." -API key: - description: "API key to connect to the Paperless-ngx API." +host: + description: "The host URL of your Paperless-ngx instance." +access_token: + description: "The API access token for the Paperless-ngx user." {% endconfiguration_basic %}
48-56: Ensure consistent sensor naming and descriptions.The sensor table entries should follow a uniform naming convention and punctuation. For example:
- Use either all noun phrases (e.g., “Total documents”) or all gerund phrases (e.g., “Number of documents”).
- Ensure every description ends with a period.
Please harmonize these for clarity.
🧹 Nitpick comments (1)
source/_integrations/paperless_ngx.markdown (1)
56-60: Remove extra blank line.There are multiple consecutive blank lines before the “Removing the integration” section. Condense to a single blank line to satisfy markdownlint rule MD012.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
57-57: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
📜 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/paperless_ngx.markdown(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
source/_integrations/paperless_ngx.markdown
57-57: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
Proposed change
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit