From 97bd98d4423af1b70f0954b903547109452724cc Mon Sep 17 00:00:00 2001 From: Trenton H <797416+stumpylog@users.noreply.github.com> Date: Tue, 13 Jan 2026 11:03:12 -0800 Subject: [PATCH] Cleaning up the documentation and adding the first migration guide --- docs/advanced_usage.md | 2 +- docs/migration.md | 19 ++++++++++++++++++ docs/troubleshooting.md | 44 +++-------------------------------------- docs/usage.md | 2 +- mkdocs.yml | 3 ++- 5 files changed, 26 insertions(+), 44 deletions(-) create mode 100644 docs/migration.md diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md index 2c8e551be..89e076167 100644 --- a/docs/advanced_usage.md +++ b/docs/advanced_usage.md @@ -501,7 +501,7 @@ The `datetime` filter formats a datetime string or datetime object using Python' See the [strftime format code documentation](https://docs.python.org/3.13/library/datetime.html#strftime-and-strptime-format-codes) for the possible codes and their meanings. -##### Date Localization +##### Date Localization {#date-localization} The `localize_date` filter formats a date or datetime object into a localized string using Babel internationalization. This takes into account the provided locale for translation. Since this must be used on a date or datetime object, diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 000000000..8953df919 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,19 @@ +# v3 Migration Guide + +## Consumer Settings Changes + +The v3 consumer command uses a [different library](https://watchfiles.helpmanual.io/) to unify +the watching for new files in the consume directory. For the user, this removes several configuration options related to delays and retries +and replaces with a single unified setting. It also adjusts how the consumer ignore filtering happens, replaced `fnmatch` with `regex` and +separating the directory ignore from the file ignore. + +### Summary + +| Old Setting | New Setting | Notes | +| ------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| `CONSUMER_POLLING` | [`CONSUMER_POLLING_INTERVAL`](configuration.md#PAPERLESS_CONSUMER_POLLING_INTERVAL) | Renamed for clarity | +| `CONSUMER_INOTIFY_DELAY` | [`CONSUMER_STABILITY_DELAY`](configuration.md#PAPERLESS_CONSUMER_STABILITY_DELAY) | Unified for all modes | +| `CONSUMER_POLLING_DELAY` | _Removed_ | Use `CONSUMER_STABILITY_DELAY` | +| `CONSUMER_POLLING_RETRY_COUNT` | _Removed_ | Automatic with stability tracking | +| `CONSUMER_IGNORE_PATTERNS` | [`CONSUMER_IGNORE_PATTERNS`](configuration.md#PAPERLESS_CONSUMER_IGNORE_PATTERNS) | **Now regex, not fnmatch** and appended to the default ignore patterns | +| _New_ | [`CONSUMER_IGNORE_DIRS`](configuration.md#PAPERLESS_CONSUMER_IGNORE_DIRS) | Additional directories to ignore and appended to the default ignore names | diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6961eb45b..570a2aa07 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -234,47 +234,9 @@ FileNotFoundError: [Errno 2] No such file or directory: '/tmp/ocrmypdf.io.yhk3zb This probably indicates paperless tried to consume the same file twice. This can happen for a number of reasons, depending on how documents are -placed into the consume folder. If paperless is using inotify (the -default) to check for documents, try adjusting the -[inotify configuration](configuration.md#inotify). If polling is enabled, try adjusting the -[polling configuration](configuration.md#polling). - -## Consumer fails waiting for file to remain unmodified. - -You might find messages like these in your log files: - -``` -[ERROR] [paperless.management.consumer] Timeout while waiting on file /usr/src/paperless/src/../consume/SCN_0001.pdf to remain unmodified. -``` - -This indicates paperless timed out while waiting for the file to be -completely written to the consume folder. Adjusting -[polling configuration](configuration.md#polling) values should resolve the issue. - -!!! note - - The user will need to manually move the file out of the consume folder - and back in, for the initial failing file to be consumed. - -## Consumer fails reporting "OS reports file as busy still". - -You might find messages like these in your log files: - -``` -[WARNING] [paperless.management.consumer] Not consuming file /usr/src/paperless/src/../consume/SCN_0001.pdf: OS reports file as busy still -``` - -This indicates paperless was unable to open the file, as the OS reported -the file as still being in use. To prevent a crash, paperless did not -try to consume the file. If paperless is using inotify (the default) to -check for documents, try adjusting the -[inotify configuration](configuration.md#inotify). If polling is enabled, try adjusting the -[polling configuration](configuration.md#polling). - -!!! note - - The user will need to manually move the file out of the consume folder - and back in, for the initial failing file to be consumed. +placed into the consume folder, such as how a scanner may modify a file multiple times as it scans. +Try adjusting the +[file stability delay](configuration.md#PAPERLESS_CONSUMER_STABILITY_DELAY) to a larger value. ## Log reports "Creating PaperlessTask failed". diff --git a/docs/usage.md b/docs/usage.md index f5c99aeaf..cac07f4a5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -565,7 +565,7 @@ This allows for complex logic to be used to generate the title, including [logic and [filters](https://jinja.palletsprojects.com/en/3.1.x/templates/#id11). The template is provided as a string. -Using Jinja2 Templates is also useful for [Date localization](advanced_usage.md#Date-Localization) in the title. +Using Jinja2 Templates is also useful for [Date localization](advanced_usage.md#date-localization) in the title. The available inputs differ depending on the type of workflow trigger. This is because at the time of consumption (when the text is to be set), no automatic tags etc. have been diff --git a/mkdocs.yml b/mkdocs.yml index 05826f25f..69a15193a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,8 +69,9 @@ nav: - development.md - 'FAQs': faq.md - troubleshooting.md + - 'Migration to v3': migration.md - changelog.md -copyright: Copyright © 2016 - 2023 Daniel Quinn, Jonas Winkler, and the Paperless-ngx team +copyright: Copyright © 2016 - 2026 Daniel Quinn, Jonas Winkler, and the Paperless-ngx team extra: social: - icon: fontawesome/brands/github