Basic docs, document some methods

docs/usage.md

@@ -254,6 +254,49 @@ These can be found under Settings > Users & Groups, assuming the user has access
 as a member of a group those permissions will be inherited and this is reflected in the UI. Explicit
 permissions can be granted to limit access to certain parts of the UI (and corresponding API endpoints).
 
+## Consumption templates
+
+Introduced in v2.0, consumption templates allow for finer control over what metadata (tags, doc types)
+and permissions (owner, privileges) are assigned to documents during consumption. In general, templates
+are applied sequentially (by sort order) but subsequent templates will never override an assignment from
+a preceding template. The same is true for mail rules, e.g. if you set the correspondent in a mail rule
+any subsequent consumption templates that are applied _will not_ overwrite this.
+
+Consumption templates allow you to filter by:
+
+- Source, e.g. documents uploaded via consume folder, API (& the web UI) and mail fetch
+- File name, including wildcards e.g. \*.pdf will apply to all pdfs
+- File path, including wildcards. Note that enabling `PAPERLESS_CONSUMER_RECURSIVE` would allow, for
+  example, automatically assigning documents to different owners based on the upload directory.
+
+!!! note
+
+    You must include a file name filter and / or a path filter. Use * for either to apply to all files.
+
+Consumption templates can assign:
+
+- Title, see [title placeholders](/usage#title_placeholders) below
+- Tags, correspondent, document types
+- Document owner
+- View and / or edit permissions to users or groups
+
+### Title placeholders
+
+Consumption template titles can include placeholders, _only for items that are assigned within the template_.
+This is because at the time of consumption (when the title is to be set), no automatic tags etc. have been
+applied. You can use the following placeholders:
+
+- `{correspondent}`: assigned correspondent name
+- `{document_type}`: assigned document type name
+- `{owner_username}`: assigned owner username
+- `{added}`: added datetime
+- `{added_year}`: added year
+- `{added_year_short}`: added year
+- `{added_month}`: added month
+- `{added_month_name}`: added month name
+- `{added_month_name_short}`: added month short name
+- `{added_day}`: added day
+
 ## Best practices {#basic-searching}
 
 Paperless offers a couple tools that help you organize your document

src/documents/consumer.py

@@ -598,6 +598,10 @@ class Consumer(LoggingMixin):
         self,
         input_doc: ConsumableDocument,
     ) -> DocumentMetadataOverrides:
+        """
+        Match consumption templates to a document based on source and
+        file name filters or path filters, if specified
+        """
         overrides = DocumentMetadataOverrides()
         for template in ConsumptionTemplate.objects.all().order_by("order"):
             template_overrides = DocumentMetadataOverrides()
@@ -657,6 +661,10 @@ class Consumer(LoggingMixin):
         return overrides
 
     def _parse_title_placeholders(self, title: str) -> str:
+        """
+        Consumption template title placeholders can only include items that are
+        assigned as part of this template (since auto-matching hasnt happened yet)
+        """
         local_added = timezone.now()
 
         correspondent_name = (
@@ -838,6 +846,10 @@ def merge_overrides(
     overridesA: DocumentMetadataOverrides,
     overridesB: DocumentMetadataOverrides,
 ) -> DocumentMetadataOverrides:
+    """
+    Merges two DocumentMetadataOverrides objects such that object B's overrides
+    are only applied if the property is empty in object A
+    """
     if overridesA.title is None:
         overridesA.title = overridesB.title
     if overridesA.tag_ids is None: