[DOCS] faq: Clarify re-download date TZ margins (#1298)

* docs(faq): Clarify re-download date TZ margins

From [Discord
discussion](https://discord.com/channels/994270357957648404/1102703969266049174/1408092149492224060).

* docs(faq): Clarify date_range inclusivity

From [PR followup](https://github.com/jmbannon/ytdl-sub/pull/1298#issuecomment-3214598919).

docs/source/config_reference/plugins.rst

@@ -147,9 +147,11 @@ Dates must adhere to a yt-dlp datetime. From their docs:
    A string in the format YYYYMMDD or
    (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s)
 
-Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this.
+Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in
-Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest
+this. Note that yt-dlp will round times to the closest day, meaning that `day` is
-granularity possible.
+the lowest granularity possible. Also note that, considering time zones, it's best
+to include a margin of an extra day on either side to be sure it includes the
+intended download files.
 
 :Usage:
 
@@ -165,14 +167,14 @@ granularity possible.
 
 :expected type: Optional[OverridesFormatter]
 :description:
-  Only download videos after this datetime.
+  Only download videos after or on this datetime, inclusive.
 
 
 ``before``
 
 :expected type: Optional[OverridesFormatter]
 :description:
-  Only download videos before this datetime.
+  Only download videos only before this datetime, not inclusive.
 
 
 ``breaks``

docs/source/faq/index.rst

@@ -195,9 +195,10 @@ need to be removed:
   the subscriptions <guides/getting_started/first_download:faster iteration cycle>` to
   download only the files that you've renamed in the steps above.
 
-  Set the appropriate dates and subscription name to include only the files you've
+  Set the appropriate dates, :ref:`including a sufficient margin
-  renamed, and re-run. For example, if you've renamed all the files from 2024 in the
+  <config_reference/plugins:date_range>`, and subscription name to include only the
-  ``NOVA PBS`` subscription:
+  files you've renamed, and re-run. For example, if you've renamed all the files from
+  2024 in the ``NOVA PBS`` subscription:
 
     .. code-block:: shell
 

src/ytdl_sub/plugins/date_range.py

@@ -25,9 +25,11 @@ class DateRangeOptions(ToggleableOptionsDictValidator):
        A string in the format YYYYMMDD or
        (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s)
 
-    Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this.
+    Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in
-    Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest
+    this. Note that yt-dlp will round times to the closest day, meaning that `day` is
-    granularity possible.
+    the lowest granularity possible. Also note that, considering time zones, it's best
+    to include a margin of an extra day on either side to be sure it includes the
+    intended download files.
 
     :Usage:
 
@@ -56,7 +58,7 @@ class DateRangeOptions(ToggleableOptionsDictValidator):
         """
         :expected type: Optional[OverridesFormatter]
         :description:
-          Only download videos before this datetime.
+          Only download videos only before this datetime, not inclusive.
         """
         return self._before
 
@@ -65,7 +67,7 @@ class DateRangeOptions(ToggleableOptionsDictValidator):
         """
         :expected type: Optional[OverridesFormatter]
         :description:
-          Only download videos after this datetime.
+          Only download videos after or on this datetime, inclusive.
         """
         return self._after
 

src/ytdl_sub/validators/string_datetime.py

@@ -12,9 +12,11 @@ class StringDatetimeValidator(OverridesStringFormatterValidator):
        A string in the format YYYYMMDD or
        (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s)
 
-    Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this.
+    Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in
-    Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest
+    this. Note that yt-dlp will round times to the closest day, meaning that `day` is
-    granularity possible.
+    the lowest granularity possible. Also note that, considering time zones, it's best
+    to include a margin of an extra day on either side to be sure it includes the
+    intended download files.
     """
 
     _expected_value_type_name = "datetime string"