[DOCS] Various clarifications (#1289)

* docs(preset): Config file top presets vs base

* docs(throttle): resolution/quality throttle asset

I also added the "wait a few hours and try again" hint, sorry I didn't think of this
when reviewing your PR. While doing that I also reformatted the `%concat(...)` arguments
to be more readable to me. Particularly to keep clear what punctuation is about argument
separation as opposed to punctuation meant to be included in the resulting string. Not a
strong preference if you don't like it.

* docs(various): Minor typo and formatting fixes

* docs(preset): Fix presets vs preset in config file

From [feedback](https://github.com/jmbannon/ytdl-sub/pull/1289#discussion_r2289960678).

* test(throttle): Match modified assertion text

If it were my test, I'd only make assertions on the spirit of error message text
necessary to confirm it's the right error message and not another.

* docs(throttle): More likely override value

From [feedback](https://github.com/jmbannon/ytdl-sub/pull/1289#discussion_r2289976156).

docs/source/config_reference/config_yaml.rst

@@ -2,10 +2,6 @@
 Configuration File
 ==================
 
-
-config.yaml
------------
-
 ytdl-sub is configured using a ``config.yaml`` file.
 
 The ``config.yaml`` is made up of two sections:
@@ -57,14 +53,28 @@ Log files are stored as
 presets
 -------
 
-``presets`` define a `formula` for how to format downloaded media and metadata.
+Each key under ``presets:`` defines a `formula` for how to format downloaded media and
+metadata. The key is the name of the preset and the value is a mapping that defines the
+preset.
 
-This section is work-in-progress!
+.. note::
+
+   The ``presets:`` key at the top of the configuration file contains multiple
+   user-defined presets, but *each preset* itself may include a ``preset:`` key that
+   defines *that preset's* base presets. For example:
+
+   .. code-block:: yaml
+
+      presets:
+        Foo Preset:
+          preset:
+            - "Jellyfin TV Show by Date"
+            - "Only Recent"
 
 preset
 ~~~~~~
 
-Presets support inheritance by defining a parent preset:
+Presets support inheritance by defining one or more parent presets:
 
 .. code-block:: yaml
 
@@ -74,11 +84,11 @@ Presets support inheritance by defining a parent preset:
     parent_preset:
       ...
     child_preset:
-      preset: "parent_preset"
+      preset:
+        - "parent_preset"
 
 In the example above, ``child_preset`` inherits all fields defined in ``parent_preset``.
-It is advantageous to use parent presets where possible to reduce duplicate yaml
-definitions.
+Use parent presets where possible to reduce duplicate yaml definitions.
 
 Presets also support inheritance from multiple presets:
 
@@ -97,8 +107,9 @@ which means:
 - if two conflicting keys arent lists or mappings, overwrite the higher priority one
 - otherwise, combine then re-evaluate
 
-If you are only inheriting from one preset, the syntax ``preset: "parent_preset"`` is
-valid YAML. Inheriting from multiple presets require use of a list.
+If you are only inheriting from one preset, using a single string instead of a list is
+valid, for example ``preset: "parent_preset"``, but we recommend always using a list for
+consistent readability between presets.
 
 .. _`mergedeep`:
    https://mergedeep.readthedocs.io/en/latest/

docs/source/guides/getting_started/index.rst

@@ -65,8 +65,8 @@ Plugins do the work
 ``ytdl-sub`` applies the plugins that the presets configure when it downloads a
 subscription. :doc:`The plugins <../../config_reference/plugins>` control how to run
 ``yt-dlp``, which media in the subscription to download, how to collect and format
-metadata for those media, and how to place the resulting files into your media library,
-and more.
+metadata for those media, how to place the resulting files into your media library, and
+more.
 
 Presets and subscriptions accept overrides
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -101,7 +101,7 @@ The configuration file extends pre-defined presets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Users define additional presets in :doc:`their configuration file <./first_config>` that
-they then use in most of their subscriptions. Most user-defines presets extend the
+they then use in most of their subscriptions. Most user-defined presets extend the
 :doc:`../../prebuilt_presets/index` provided by ``ytdl-sub``.
 
 Caveats

docs/source/guides/install/docker.rst

@@ -119,5 +119,5 @@ Configuration
 
 In these examples, the configuration files will be at
 ``<path/to/ytdl-sub/config>/config.yaml`` and
-``<path/to/ytdl-sub/config>/subscriptions.yaml``. Starting the container the first time
-will populate those files with default examples.
+``<path/to/ytdl-sub/config>/subscriptions.yaml``. Start the container the first time to
+populate those files with default examples.

docs/source/introduction.rst

@@ -17,9 +17,13 @@ and how it should appear in your media library servers and applications such as
 To these ends, ``ytdl-sub``:
 
 - wraps and runs `yt-dlp`_, per your configuration to:
+
   - download the media, remux and/or optionally transcode it
+
 - prepares additional metadata both embedded and in external files
+
 - renames the resulting files
+
 - places them in your library
 
 .. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG

docs/source/prebuilt_presets/helpers.rst

@@ -140,3 +140,39 @@ default. You can change this number by setting the override variable
 Once the entire channel is downloaded, remove the usage of this preset. It will then
 pull metadata from newest to oldest again, and stop once it reaches a video that has
 already been downloaded.
+
+
+_throttle_protection
+--------------------
+
+.. note::
+
+   This preset is already a base preset of those higher-level presets that require it,
+   so users seldom need to use it directly, for example, unless they're writing presets
+   from scratch.
+
+This preset is primarily a sensible default configuration of :ref:`the
+'throttle_protection' plugin <config_reference/plugins:throttle_protection>` along with
+an override to disable the plugin:
+
+.. code-block:: yaml
+
+   overrides:
+     # Disable throttle protection:
+     enable_throttle_protection: false
+
+In addition to throttling by denying download requests, some services also throttle
+downloads by only allowing downloads of the lowest resolution quality. At the time of
+writing, only YouTube does this by allowing only 360p downloads when throttled. To work
+around this kind of throttling, this preset includes :ref:`an assertion
+<config_reference/scripting/scripting_functions:error functions>` that will stop
+downloading when ``ytdl-sub`` downloads a video at 360p or lower. It supports the
+following overrides:
+
+.. code-block:: yaml
+
+   overrides:
+     # Disable resolution quality throttle protection:
+     enable_resolution_assert: false
+     # Change the resolution below which to assume downloading is throttled:
+     resolution_assert_height_gte: 720

src/ytdl_sub/prebuilt_presets/helpers/throttle_protection.yaml

@@ -58,8 +58,13 @@ presets:
             %assert(
               %gte( height, resolution_assert_height_gte ),
               %concat(
-                "Entry ", title, " downloaded at a low resolution (", resolution_readable, ") which is classified as throttle. ",
-                "Stopping additional downloads. Disable using the override variable `enable_resolution_assert: False`"
+                "Entry ",
+                title,
+                " downloaded at a low resolution (",
+                resolution_readable,
+                "), you've probably been throttled. ",
+                "Stopping further downloads, wait a few hours and try again. ",
+                "Disable using the override variable `enable_resolution_assert: False`."
               )
             ),
             "false is no-op"

tests/integration/plugins/test_throttle_protection.py

@@ -271,8 +271,10 @@ class TestResolutionAssert:
         )
 
         expected_message = (
-            "Entry Mock Entry 20-3 downloaded at a low resolution (640x360) which is classified as throttle. "
-            "Stopping additional downloads. Disable using the override variable `enable_resolution_assert: False`"
+            "Entry Mock Entry 20-3 downloaded at a low resolution (640x360), "
+            "you've probably been throttled. "
+            "Stopping further downloads, wait a few hours and try again. "
+            "Disable using the override variable `enable_resolution_assert: False`"
         )
 
         with (