docs(config): Clarify persist_logs behavior/opts

Clarify the `persist_logs:` options per [Discord discussion](https://discord.com/channels/994270357957648404/1409161361853780060/1409602529460879431).

docs/source/config_reference/config_yaml.rst

@@ -33,8 +33,17 @@ subscriptions.
 persist_logs
 ~~~~~~~~~~~~
 
-Within ``configuration``, define whether logs from subscription downloads should be
+Without this key, ``ytdl-sub`` only prints output to it's ``stdout`` and ``stderr``. If
-persisted.
+your configuration includes the ``persist_logs:`` key, then ``ytdl-sub`` also writes log
+files to disk.
+
+.. warning::
+
+   The log files grow rapidly if ``keep_successful_logs:`` is ``true``, the default, and
+   may fill up disk space. Set ``keep_successful_logs: false`` or prune the log files
+   regularly.
+
+For example:
 
 .. code-block:: yaml
 
@@ -42,9 +51,6 @@ persisted.
     persist_logs:
       logs_directory: "/path/to/log/directory"
 
-Log files are stored as
-``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``.
-
 .. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator()
   :members:
   :member-order: bysource

examples/advanced/tv_show_config.yaml

@@ -1,9 +1,9 @@
 ###############################################################################
-# Top-level configurations to apply umask and persist error logs
+# Top-level configurations to apply umask and write log files
 configuration:
   umask: "002"
   persist_logs:
-    logs_directory: './logs'
+    logs_directory: '/config/logs'
     keep_successful_logs: False
 
 presets:
@@ -98,4 +98,4 @@ presets:
 
     overrides:
       only_recent_date_range: "2months"
-      only_recent_max_files: 30
+      only_recent_max_files: 30

src/ytdl_sub/config/config_validator.py

@@ -67,7 +67,8 @@ class PersistLogsValidator(StrictDictValidator):
     @property
     def logs_directory(self) -> str:
         """
-        The directory to store the logs in. (required)
+        Write log files to this directory with names like
+        ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required)
         """
         return self._logs_directory.value
 
@@ -92,7 +93,10 @@ class PersistLogsValidator(StrictDictValidator):
     @property
     def keep_successful_logs(self) -> bool:
         """
-        Whether to store logs when downloading is successful. (default ``True``)
+        If the ``persist_logs:`` key is in the configuration, then ``ytdl-sub`` *always*
+        writes log files for the subscription both for successful downloads and when it
+        encounters an error while downloading. When this key is ``False``, only write
+        log files for errors. (default ``True``)
         """
         return self._keep_successful_logs.value