Merge pull request #205 from flyingcircusio/improve-trash-docs

Improve documentation of `batou_ext.file.DeploymentTrash`

CHANGES.d/20241209_075336_cz_improve_trash_docs.md

@@ -0,0 +1 @@
+- Improve documentation of `batou_ext.file.DeploymentTrash`

src/batou_ext/file.py

@@ -148,20 +148,25 @@ def update(self):
 
 
 class DeploymentTrash(batou.component.Component):
-    """
-    A trash folder that is regularly cleaned up by systemd's tmpfiles.
-    Files and Folders can be moved in here for asynchronous deletion that is not tied to the deployment.
-    Due to this component being commonly used to offload deleting very large files, it also supports adding IOPS limits.
+    """A trash folder that is regularly cleaned up by systemd's tmpfiles.
+
+    Files and Folders can be moved in here for asynchronous deletion that is
+    not tied to the deployment. Due to this component being commonly used to
+    offload deleting very large files, it also supports adding IOPS limits.
 
 
     ```python
-    self.trash = DeploymentTrash(read_iops_limit = 250, write_iops_limit = 250)
-    self += self.trash
+    def configure(self):
+        self.trash = DeploymentTrash(read_iops_limit=250, write_iops_limit=250)
+        self += self.trash
+
+    def update(self):
+        # files that are created here should not be part of the deployment but
+        # rather a sideproduct for example a cache directory or build artefacts
+        # that are generated by some script
+        large_folder = do_something_that_generates_a_lot_of_byproducts()
+        self.trash.discard(large_folder)
 
-    # files that are created here should not be part of the deployment but rather a sideproduct
-    # for example a cache directory or build artefacts that are generated by some script
-    large_folder = do_something_that_generates_a_lot_of_byproducts()
-    self.trash.discard(large_folder)
     ```
     """