[DOCS] Consistent headings, newlines, wraps (#1293)

I've been running into variations in style in the docs I've edited so far. I've been
including changes for consistency in with other commits but in many cases that makes one
part of one doc more consistent with the rest but less consistent with itself. It seems
like a bit of cleanup may be in order.

This change applies the following conventions:

- Section heading heirarchy:
  #. ``=`` with overline for document title, IOW first heading
  #. ``-``
  #. ``~``
  #. ``"``

- Two newlines before ``-`` sections for readability

- A newline between every section of any level and the first line of text

- Wrap paragraph lines at 88 characters to match Python's Black

I've only applied these changes to those ``*.rst`` files that aren't generated.

In the future, I might suggest another bulk change to match [the Sphinx conventions for
section
headings](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections).

docs/source/config_reference/config_yaml.rst

@@ -1,7 +1,8 @@
 ==================
 Configuration File
 ==================
------------
+
+
 config.yaml
 -----------
 
@@ -14,17 +15,19 @@ The ``config.yaml`` is made up of two sections:
   configuration:
   presets:
 
-You can jump to any section and subsection of the config using the navigation
+You can jump to any section and subsection of the config using the navigation section to
-section to the left.
+the left.
 
 Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``.
-If you wish to represent paths like Windows, you will need to ``C:\\double\\bashslash\\paths``
+If you wish to represent paths like Windows, you will need to
-in order to escape the backslash character.
+``C:\\double\\bashslash\\paths`` in order to escape the backslash character.
+
 
 configuration
-~~~~~~~~~~~~~
+-------------
-The ``configuration`` section contains app-wide configs applied to all presets
+
-and subscriptions.
+The ``configuration`` section contains app-wide configs applied to all presets and
+subscriptions.
 
 .. autoclass:: ytdl_sub.config.config_validator.ConfigOptions()
   :members:
@@ -32,9 +35,10 @@ and subscriptions.
   :exclude-members: subscription_value, persist_logs, experimental
 
 persist_logs
-""""""""""""
+~~~~~~~~~~~~
-Within ``configuration``, define whether logs from subscription downloads
+
-should be persisted.
+Within ``configuration``, define whether logs from subscription downloads should be
+persisted.
 
 .. code-block:: yaml
 
@@ -49,14 +53,17 @@ Log files are stored as
   :members:
   :member-order: bysource
 
+
 presets
-~~~~~~~
+-------
+
 ``presets`` define a `formula` for how to format downloaded media and metadata.
 
 This section is work-in-progress!
 
 preset
-""""""
+~~~~~~
+
 Presets support inheritance by defining a parent preset:
 
 .. code-block:: yaml

docs/source/config_reference/index.rst

@@ -2,7 +2,8 @@
 Reference
 =========
 
-This section contains direct references to the code of ``ytdl-sub`` and information on how it functions.
+This section contains direct references to the code of ``ytdl-sub`` and information on
+how it functions.
 
 
 Terminology

docs/source/config_reference/prebuilt_presets/common.rst

@@ -4,22 +4,30 @@ Common
 
 .. highlight:: yaml
 
+
 Filter Keywords
 ---------------
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/helpers/filter_keywords.yaml
+
 
 Filter Duration
 ---------------
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/helpers/filter_duration.yaml
+
 
 Media Quality
 -------------
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml
+
 
 Only Recent Videos
 ------------------
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml

docs/source/config_reference/prebuilt_presets/index.rst

@@ -2,11 +2,10 @@
 Prebuilt Preset Reference
 =========================
 
-This section contains the code for the prebuilt presets. If you just want to understand how to use the presets, check :doc:`this section instead</prebuilt_presets/index>`.
+This section contains the code for the prebuilt presets. If you just want to understand
-
+how to use the presets, check :doc:`this section instead</prebuilt_presets/index>`.
-
 
 .. toctree::
   common
   tv_show
-  music
+  music

docs/source/config_reference/prebuilt_presets/music.rst

@@ -6,4 +6,5 @@ All audio music based presets inherit from ``_music_base``.
 
 .. highlight:: yaml
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml

docs/source/config_reference/prebuilt_presets/tv_show.rst

@@ -6,4 +6,5 @@ All TV show based presets inherit from ``_episode_base``.
 
 .. highlight:: yaml
 
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml
+.. literalinclude::
+   /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml

docs/source/config_reference/scripting/index.rst

@@ -2,8 +2,9 @@
 Scripting
 =========
 
-``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The links below
+``ytdl-sub`` fields (file-names, tags, etc) are defined using variables and scripts. The
-contain reference documentation for each built-in variable and scripting function.
+links below contain reference documentation for each built-in variable and scripting
+function.
 
 .. toctree::
   :maxdepth: 1
@@ -13,6 +14,7 @@ contain reference documentation for each built-in variable and scripting functio
   scripting_functions
   scripting_types
 
+
 How it Works
 ------------
 
@@ -44,22 +46,22 @@ We can use this instead of hard-coding it above:
      output_directory: "/path/to/tv_shows/{subscription_name}"
 
 The syntax for variable usage is curly-braces with the variable name within it. Assuming
-our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub``
+our subscription is actually named "Custom YTDL-SUB TV Show", then ``ytdl-sub`` will
-will actually write to that directory.
+actually write to that directory.
 
 Entry Variables
 ~~~~~~~~~~~~~~~
 
-For context, an *entry* is a video or audio file downloaded from ``yt-dlp``.
+For context, an *entry* is a video or audio file downloaded from ``yt-dlp``.  *Entry
-*Entry variables* are variables that are derived from an entry's ``info.json`` file. This file
+variables* are variables that are derived from an entry's ``info.json`` file. This file
 comes from ``yt-dlp`` and contains every piece of metadata that it scraped.
 
-These variables are not considered static since they change per entry download. There are a
+These variables are not considered static since they change per entry download. There
-few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For others,
+are a few fields in ``ytdl-sub`` (i.e. ``output_directory``) that must be static. For
-we are free to use values that derive from an entry.
+others, we are free to use values that derive from an entry.
 
-Suppose we want to customize the name of an entry's output file and thumbnail to include its
+Suppose we want to customize the name of an entry's output file and thumbnail to include
-title in its name. We can do that using entry variables:
+its title in its name. We can do that using entry variables:
 
 .. code-block:: yaml
 
@@ -74,8 +76,8 @@ Creating Custom Variables
 Suppose we want to include the date in our file names. This means we'd need to update
 both the ``file_name`` and ``thumbnail_name`` fields to include it.
 
-Instead, we can create a custom *override variable*. This is ``ytdl-sub``'s method
+Instead, we can create a custom *override variable*. This is ``ytdl-sub``'s method for
-for creating and overriding custom variables.
+creating and overriding custom variables.
 
 These are created in the ``overrides`` section. Let's take our above example and create
 a ``custom_file_name`` variable to use for the entry file and thumbnail fields:
@@ -97,9 +99,9 @@ For experienced ``yt-dlp`` scrapers, you may be thinking:
 
 - What if the title has characters that do not play nice with my operating system?
 
-``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic characters
+``ytdl-sub`` is able to *sanitize* any variable, meaning it replaces any problematic
-with safe alternatives that can be used in file names. We can ensure our file names and directories
+characters with safe alternatives that can be used in file names. We can ensure our file
-are safe by using:
+names and directories are safe by using:
 
 .. code-block:: yaml
 
@@ -116,16 +118,16 @@ Simply add a ``_sanitized`` suffix to any variable name to make it sanitized.
 .. note::
 
    Make sure you do not sanitize custom variables that intentionally create directories,
-   (i.e. sanitizing ``/path/to/tv_shows/``) otherwise they will... be sanitized and not resolve to
+   (i.e. sanitizing ``/path/to/tv_shows/``) otherwise they will... be sanitized and not
-   directories!
+   resolve to directories!
 
 
 Using Scripting Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Let's suppose you are an avid command-line user, and like all of your file names to be
-``snake_cased_with_no_spaces``. We can use the
+``snake_cased_with_no_spaces``. We can use the `replace
-`replace <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#replace>`_
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#replace>`_
 *scripting function* to create and use a snake-cased title.
 
 .. code-block:: yaml
@@ -143,42 +145,48 @@ Let's suppose you are an avid command-line user, and like all of your file names
      custom_file_name: "{upload_date_standardized}_{snake_cased_title_sanitized}"
 
 Scripting functions are similar to variables - they must be used within curly-braces.
-It is good practice to use ``>-`` when defining variables that use functions. It is YAML's way of
+It is good practice to use ``>-`` when defining variables that use functions. It is
-saying:
+YAML's way of saying:
 
 - Allow a string to be multi-lined, and do not include newlines before or after it.
 
-See for yourself `here <https://yaml-online-parser.appspot.com/?yaml=output_options%3A%0A%20%20output_directory%3A%20%22%7Bsubscription_name_sanitized%7D%22%0A%20%20file_name%3A%20%22%7Bcustom_file_name%7D.%7Bext%7D%22%0A%20%20thumbnail_name%3A%20%22%7Bcustom_file_name%7D.%7Bthumbnail_ext%7D%22%0A%0Aoverrides%3A%0A%20%20snake_cased_title%3A%20%3E-%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%25replace%28%20title%2C%20%27%20%27%2C%20%27_%27%20%29%0A%20%20%20%20%7D%0A%20%20custom_file_name%3A%20%22%7Bupload_date_standardized%7D%20%7Bsnake_cased_title_sanitized%7D%22&type=json>`_.
+See for yourself `here
-Any whitespace within curly-braces is okay since it will be parsed out. This is needed to make
+<https://yaml-online-parser.appspot.com/?yaml=output_options%3A%0A%20%20output_directory%3A%20%22%7Bsubscription_name_sanitized%7D%22%0A%20%20file_name%3A%20%22%7Bcustom_file_name%7D.%7Bext%7D%22%0A%20%20thumbnail_name%3A%20%22%7Bcustom_file_name%7D.%7Bthumbnail_ext%7D%22%0A%0Aoverrides%3A%0A%20%20snake_cased_title%3A%20%3E-%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%25replace%28%20title%2C%20%27%20%27%2C%20%27_%27%20%29%0A%20%20%20%20%7D%0A%20%20custom_file_name%3A%20%22%7Bupload_date_standardized%7D%20%7Bsnake_cased_title_sanitized%7D%22&type=json>`_.
-scripting function usage readable.
+Any whitespace within curly-braces is okay since it will be parsed out. This is needed
+to make scripting function usage readable.
 
 .. important::
 
-   It is important to use ``>-`` over other YAML new-line directives like ``>`` because they
+   It is important to use ``>-`` over other YAML new-line directives like ``>`` because
-   add newlines before or after curly-braces, and will be included in your variable's output string.
+   they add newlines before or after curly-braces, and will be included in your
+   variable's output string.
+
 
 Advanced Scripting
 ------------------
 
 Accessing ``info.json`` Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The entirety of an entry's ``info.json`` file resides in the
-`Map <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_types.html#map>`_
-variable
-`entry_metadata <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/entry_variables.html#entry-metadata>`_.
 
-Any field can be accessed by using the
+The entirety of an entry's ``info.json`` file resides in the `Map
-`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_types.html#map>`_
+variable `entry_metadata
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/entry_variables.html#entry-metadata>`_.
+
+Any field can be accessed by using the `map_get
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
 function like so:
 
 .. code-block:: yaml
-  :caption: Fetches the 'artist' value from the .info.json, returns null if it does not exist.
+  :caption:
+     Fetches the 'artist' value from the .info.json, returns null if it does not exist.
 
    artist: >-
      { %map_get( entry_metadata, "artist", null ) }
 
 Creating Custom Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Custom functions can be created in the overrides section using the following syntax:
 
 .. code-block:: yaml
@@ -187,9 +195,9 @@ Custom functions can be created in the overrides section using the following syn
      "%get_entry_metadata_field": >-
        { %map_get( entry_metadata, $0, null ) }
 
-Custom function definitions must have ``%`` as a prefix to the function name, be surrounded by
+Custom function definitions must have ``%`` as a prefix to the function name, be
-quotes to make YAML parsing happy, and can support arguments using ``$0``, ``$1``, ... to indicate
+surrounded by quotes to make YAML parsing happy, and can support arguments using ``$0``,
-their first argument, second argument, etc.
+``$1``, ... to indicate their first argument, second argument, etc.
 
 Using our new custom function, we can simply the ``artist`` variable definition above to:
 

docs/source/config_reference/scripting/scripting_types.rst

@@ -1,7 +1,8 @@
-
+===============
 Scripting Types
 ===============
 
+
 Types
 -----
 
@@ -16,8 +17,9 @@ Strings are a series of characters surrounded by quotes.
 
 .. note::
 
-   For non-String types, they must be defined as parameters to scripting functions. This is because
+   For non-String types, they must be defined as parameters to scripting functions. This
-   anything in a variable definition that is not within curly-braces gets evaluated as a String.
+   is because anything in a variable definition that is not within curly-braces gets
+   evaluated as a String.
 
 We can define Strings within curly-braces by setting them as parameters to a function:
 
@@ -65,8 +67,8 @@ There are a few ways to make variables that use curly braces more compact, inclu
 
       string_variable: "{ %string('This is a String variable') }"
 
-In the case that you want to define a string variable that contains both single and double quotes,
+In the case that you want to define a string variable that contains both single and
-triple-quotes can be used to avoid *closing* the String.
+double quotes, triple-quotes can be used to avoid *closing* the String.
 
 .. tab-set::
 
@@ -88,7 +90,8 @@ triple-quotes can be used to avoid *closing* the String.
           %string("""This has both " and ' in it.""")
         }
 
-If you want a plain string that contains literal curly braces, you can escape them like so:
+If you want a plain string that contains literal curly braces, you can escape them like
+so:
 
 .. code-block:: yaml
 
@@ -185,8 +188,8 @@ A type is considered boolean if it spells out ``True`` or ``False``, case-insens
 Array
 ~~~~~
 
-An Array contains multiple types of any kind, including nested Arrays and Maps.
+An Array contains multiple types of any kind, including nested Arrays and Maps.  Arrays
-Arrays are defined using brackets (``[ ]``), and are accessed using zero-based indexing.
+are defined using brackets (``[ ]``), and are accessed using zero-based indexing.
 
 .. tab-set::
 
@@ -227,8 +230,8 @@ Arrays are defined using brackets (``[ ]``), and are accessed using zero-based i
 Map
 ~~~
 
-A Map is a key-value store, containing mappings between keys and values.
+A Map is a key-value store, containing mappings between keys and values.  Maps are
-Maps are defined using curly-braces (``{ }``), and are accessed using their keys.
+defined using curly-braces (``{ }``), and are accessed using their keys.
 
 .. tab-set::
 
@@ -267,6 +270,7 @@ Maps are defined using curly-braces (``{ }``), and are accessed using their keys
 
 Null
 ~~~~
+
 Null is represented by an empty String, and can be conveyed by spelling out ``null``,
 case-insensitive.
 
@@ -297,7 +301,9 @@ Function Type-Hints
 
 AnyArgument
 ~~~~~~~~~~~
-AnyArgument means any of the above Types are valid as input or output to a scripting function.
+
+AnyArgument means any of the above Types are valid as input or output to a scripting
+function.
 
 .. note::
 
@@ -306,13 +312,15 @@ AnyArgument means any of the above Types are valid as input or output to a scrip
 
 Numeric
 ~~~~~~~
+
 Numeric refers to either an Integer or Float.
 
 Optional
 ~~~~~~~~
-Optional means a particular scripting function argument can be either provided or not included.
+
-For example, the function
+Optional means a particular scripting function argument can be either provided or not
-`map_get <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
+included.  For example, the function `map_get
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#map-get>`_
 has an optional default value. Both of these usages are valid:
 
 .. tab-set::
@@ -331,8 +339,9 @@ has an optional default value. Both of these usages are valid:
 
 Lambda
 ~~~~~~
-Lambda parameters are a reference to a function, and will call that lambda function
+
-on the input. In this example,
+Lambda parameters are a reference to a function, and will call that lambda function on
+the input. In this example,
 
 .. code-block:: yaml
 
@@ -341,20 +350,23 @@ on the input. In this example,
        %array_apply( [ 1, 2, 3, 4], %string )
      }
 
-We apply ``%string`` as a lambda function to
+We apply ``%string`` as a lambda function to `array_apply
-`array_apply <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-apply>`_,
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-apply>`_,
-which is called on every element in the input array. The output becomes ``["1", "2", "3", "4"]``.
+which is called on every element in the input array. The output becomes ``["1", "2",
+"3", "4"]``.
 
-This example has one input-argument being passed into the lambda. For other lambda-based functions
+This example has one input-argument being passed into the lambda. For other lambda-based
-like `array_enumerate <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-enumerate>`_,
+functions like `array_enumerate
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-enumerate>`_,
 it expects the lambda function to have two input arguments. These are denoted using
 ``LambdaTwo``, ``LambdaThree``, etc within the function spec.
 
 LambdaReduce
 ~~~~~~~~~~~~
-LambdaReduce parameters are a reference to a function that will perform a *reduce* - an operation
+
-that reduces an Array to a single value by calling the LambdaReduce function repeatedly on two
+LambdaReduce parameters are a reference to a function that will perform a *reduce* - an
-elements in the Array until it is reduced to a single value.
+operation that reduces an Array to a single value by calling the LambdaReduce function
+repeatedly on two elements in the Array until it is reduced to a single value.
 
 In this example,
 
@@ -365,11 +377,12 @@ In this example,
        %array_reduce( [ 1, 2, 3, 4], %add )
      }
 
-We call
+We call `array_reduce
-`array_reduce <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#array-reduce>`_
-on the input array, using
+on the input array, using `add
-`add <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#add>`_
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#add>`_
-as the LambdaReduce function. This will reduce the Array to a single value by internally calling
+as the LambdaReduce function. This will reduce the Array to a single value by internally
+calling
 
 - *reduce-call 1*: ``%add(1, 2) = 3`` (first two elements)
 - *reduce-call 2*: ``%add(3, 3) = 6`` (output from first two and third element)
@@ -380,9 +393,10 @@ And evaluate to ``10``.
 ReturnableArguments
 ~~~~~~~~~~~~~~~~~~~
 
-Returnable arguments are used in conditional functions like
+Returnable arguments are used in conditional functions like `if
-`if <https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#if>`_,
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/scripting/scripting_functions.html#if>`_,
-which implies the argument passed into the function is the function's output. For example,
+which implies the argument passed into the function is the function's output. For
+example,
 
 .. code-block:: yaml
 
@@ -391,4 +405,4 @@ which implies the argument passed into the function is the function's output. Fo
        %if( True, "Return this if True", "Return this if False" )
      }
 
-is going to return ``"Return this if True"`` since the condition parameter is ``True``.
+is going to return ``"Return this if True"`` since the condition parameter is ``True``.

docs/source/config_reference/subscription_yaml.rst

@@ -2,19 +2,22 @@
 Subscription File
 ==================
 
-A subscription file is designed to both define and organize many things
+A subscription file is designed to both define and organize many things to download in
-to download in condensed YAML.
+condensed YAML.
 
 .. hint::
 
   Read the :ref:`getting started guide <guides/getting_started/index:Getting Started>`
   first before reviewing this section.
 
+
 File Preset
 -----------
-Many examples show ``__preset__`` at the top. This is known as the *subscription file preset*.
+
-It is where a single :ref:`preset <guides/getting_started/first_config:Custom Preset Definition>`
+Many examples show ``__preset__`` at the top. This is known as the *subscription file
-can be defined that gets applied to each subscription within the file.
+preset*.  It is where a single :ref:`preset <guides/getting_started/first_config:Custom
+Preset Definition>` can be defined that gets applied to each subscription within the
+file.
 
 This is a good place to apply file-wide variables such as ``tv_show_directory`` or
 supply a cookies file path.
@@ -28,9 +31,9 @@ supply a cookies file path.
     ytdl_options:
       cookiefile: "/config/cookie.txt"
 
-
 Layout
 ------
+
 A subscription file is comprised of YAML keys and values. Keys can be either
 
 - a preset
@@ -52,32 +55,33 @@ All three types of keys are used for the following:
 - ``= News`` - an override value for genre
 - ``Breaking News``, ``BBC News`` - The subscription names
 
-The lowest level, most indented keys should always be the subscription name.
+The lowest level, most indented keys should always be the subscription name.  It is good
-It is good practice to put subscription names in quotes to differentiate
+practice to put subscription names in quotes to differentiate between preset names and
-between preset names and subscription names.
+subscription names.
 
-Values should always be the subscription itself. The simplest form is
+Values should always be the subscription itself. The simplest form is just the
-just the URL. Further sections will show more exotic examples that go beyond
+URL. Further sections will show more exotic examples that go beyond a single URL.
-a single URL.
 
 
 Inheritance
 -----------
-A subscription inherits every key above it. In the above example,
+
-both ``Breaking News`` and ``BBC News`` inherits the ``Jellyfin TV Show by Date``
+A subscription inherits every key above it. In the above example, both ``Breaking News``
-preset and the ``= News`` override value.
+and ``BBC News`` inherits the ``Jellyfin TV Show by Date`` preset and the ``= News``
+override value.
 
 .. note::
 
-  There are no limits or boundaries on how one structures
+  There are no limits or boundaries on how one structures their presets. This
-  their presets. This flexibility is intended for subscription authors
+  flexibility is intended for subscription authors to organize their downloads as they
-  to organize their downloads as they see fit.
+  see fit.
+
 
 Multi Keys
 ----------
-Subscription keys support pipe syntax, or ``|``, which allows multiple
+
-keys to be defined on a single line. The following is equivalent to the above
+Subscription keys support pipe syntax, or ``|``, which allows multiple keys to be
-example:
+defined on a single line. The following is equivalent to the above example:
 
 .. code-block:: yaml
 
@@ -85,16 +89,16 @@ example:
     "Breaking News": "https://www.youtube.com/@SomeBreakingNews"
     "BBC News": "https://www.youtube.com/@BBCNews"
 
+
 Override Mode
 -------------
-Often times, it is convenient to set multiple override values for
+
-a single subscription. We can put a preset in *override mode* by
+Often times, it is convenient to set multiple override values for a single
-using tilda syntax, or ``~``.
+subscription. We can put a preset in *override mode* by using tilda syntax, or ``~``.
 
 Suppose we want to apply the :ref:`Only Recent <prebuilt_presets/helpers:Only Recent>`
-preset to the above examples. But for ``BBC News`` specifically, we want to
+preset to the above examples. But for ``BBC News`` specifically, we want to set the date
-set the date range to be different than the default ``2months`` value to
+range to be different than the default ``2months`` value to ``2weeks``.
-``2weeks``.
 
 We can change it as follows:
 
@@ -109,13 +113,14 @@ We can change it as follows:
 
 .. important::
 
-  When using override mode, we need to set the ``url``
+  When using override mode, we need to set the ``url`` variable since we are no longer
-  variable since we are no longer using the simplified
+  using the simplified *subscription_value*. For more info on how this works, read about
-  *subscription_value*. For more info on how this works,
+  :ref:`subscription variables <config_reference/scripting/static_variables:Subscription
-  read about :ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
+  Variables>`.
+
 
 Map Mode
 --------
-Map mode is for highly advanced presets that benefit
+
-from a more complex subscription definition. TODO: Show music video
+Map mode is for highly advanced presets that benefit from a more complex subscription
-example here.
+definition. TODO: Show music video example here.

docs/source/deprecation_notices.rst

@@ -1,14 +1,16 @@
 Deprecation Notices
 ===================
 
+
 Sep 2024
 --------
 
 regex plugin
 ~~~~~~~~~~~~
+
 Regex plugin has been removed in favor of scripting. The function
-:ref:`config_reference/scripting/scripting_functions:regex_capture_many`
+:ref:`config_reference/scripting/scripting_functions:regex_capture_many` has been
-has been created to replicate the plugin's behavior. See the following converted example:
+created to replicate the plugin's behavior. See the following converted example:
 
 .. code-block:: yaml
   :caption: regex plugin
@@ -40,13 +42,16 @@ has been created to replicate the plugin's behavior. See the following converted
         }
       track_title: "{%array_at(captured_track_title, 1)}"
 
+
 Oct 2023
 --------
 
 subscription preset and value
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The use of ``__value__`` will go away in Dec 2023 in favor of the method found in
-:ref:`config_reference/subscription_yaml:Subscription File`. ``__preset__`` will still be supported for the time being.
+:ref:`config_reference/subscription_yaml:Subscription File`. ``__preset__`` will still
+be supported for the time being.
 
 July 2023
 ---------
@@ -54,8 +59,9 @@ July 2023
 music_tags
 ~~~~~~~~~~
 
-Music tags are getting simplified. ``tags`` will now reside directly under music_tags, and
+Music tags are getting simplified. ``tags`` will now reside directly under music_tags,
-``embed_thumbnail`` is getting moved to its own plugin (supports video files as well). Convert from:
+and ``embed_thumbnail`` is getting moved to its own plugin (supports video files as
+well). Convert from:
 
 .. code-block:: yaml
 
@@ -79,8 +85,8 @@ The old format will be removed in October 2023.
 video_tags
 ~~~~~~~~~~
 
-Video tags are getting simplified as well. ``tags`` will now reside directly under video_tags.
+Video tags are getting simplified as well. ``tags`` will now reside directly under
-Convert from:
+video_tags.  Convert from:
 
 .. code-block:: yaml
 

docs/source/faq/index.rst

@@ -2,20 +2,23 @@
 FAQ
 ===
 
-Since ytdl-sub is relatively new to the public, there has not been many question asked yet. We will update this as more questions get asked.
+Since ytdl-sub is relatively new to the public, there has not been many question asked
+yet. We will update this as more questions get asked.
 
 .. contents:: Frequently Asked Questions
   :depth: 3
 
+
 How do I...
 -----------
 
 ...remove the date in the video title?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default include the upload date in the ``episode_title``
+The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default include
-override variable. This variable is used to set the title in things like the video metadata, NFO file, etc, which is
+the upload date in the ``episode_title`` override variable. This variable is used to set
-subsequently read by media players. This can be overwritten as you see fit by redefining it:
+the title in things like the video metadata, NFO file, etc, which is subsequently read
+by media players. This can be overwritten as you see fit by redefining it:
 
 .. code-block:: yaml
 
@@ -31,16 +34,24 @@ If you need support, you can:
 
 * `Join our Discord <https://discord.gg/v8j9RAHb4k>`_
 
-If you would like to contribute, we're happy to accept any help, even non-coders! To find out how you can help this project, you can:
+If you would like to contribute, we're happy to accept any help, even non-coders! To
+find out how you can help this project, you can:
 
-* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in #development with where you think you can assist or what skills you would like to contribute.
+* `Join our Discord <https://discord.gg/v8j9RAHb4k>`_ and leave a comment in
+  #development with where you think you can assist or what skills you would like to
+  contribute.
 
-* If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull request <compare>` with information on what issue you're resolving and it will be reviewed as soon as possible.
+* If you just want to fix one thing, you're welcome to :ytdl-sub-gh:`submit a pull
+  request <compare>` with information on what issue you're resolving and it will be
+  reviewed as soon as possible.
 
 ...download age-restricted YouTube videos?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See `yt-dl's recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_ to download your YouTube cookie, then add it to your :ref:`ytdl options <config_reference/plugins:ytdl_options>` section of your config:
+See `yt-dl's recommended way
+<https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_ to
+download your YouTube cookie, then add it to your :ref:`ytdl options
+<config_reference/plugins:ytdl_options>` section of your config:
 
 .. code-block:: yaml
 
@@ -50,7 +61,8 @@ See `yt-dl's recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pa
 ...automate my downloads?
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:doc:`This page </guides/getting_started/automating_downloads>` shows how to set up ``ytdl-sub`` to run automatically on various platforms.
+:doc:`This page </guides/getting_started/automating_downloads>` shows how to set up
+``ytdl-sub`` to run automatically on various platforms.
 
 ...download large channels?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -65,7 +77,8 @@ See the prebuilt preset :doc:`Filter Keywords </prebuilt_presets/helpers>`.
 ...prevent creation of NFO file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, can be disabled:
+Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, can be
+disabled:
 
 .. code-block:: yaml
 
@@ -75,8 +88,9 @@ Creation of NFO files is done by the NFO tags plugin. It, as any other plugin, c
 ...prevent download of images
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default downloads images corresponding to show and each episode.
+The :ref:`config_reference/prebuilt_presets/tv_show:TV Show` presets by default
-This can be prevented by overriding following variables:
+downloads images corresponding to show and each episode.  This can be prevented by
+overriding following variables:
 
 .. code-block:: yaml
 
@@ -88,10 +102,11 @@ This can be prevented by overriding following variables:
 ...use only part of the media's title
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-ytdl-sub offers a range of functions that can be used to parse a subset of a title
+ytdl-sub offers a range of functions that can be used to parse a subset of a title for
-for use in your media player. Consider the example:
+use in your media player. Consider the example:
 
-* I want to remove "NOVA PBS - " from the title ``NOVA PBS - Hidden Cities All Around Us``.
+* I want to remove "NOVA PBS - " from the title ``NOVA PBS - Hidden Cities All Around
+  Us``.
 
 There are several solutions using ytdl-sub's scripting capabilities to override
 ``episode_title`` by manipulating the original media's ``title``.
@@ -117,7 +132,9 @@ There are several solutions using ytdl-sub's scripting capabilities to override
        }
 
 .. code-block:: yaml
-   :caption: Regex capture. Supports multiple capture strings and default values if captures are unsuccessful.
+   :caption:
+      Regex capture. Supports multiple capture strings and default values if captures
+      are unsuccessful.
 
    "~Nova PBS":
      url: "https://www.youtube.com/@novapbs"
@@ -132,10 +149,10 @@ There are several solutions using ytdl-sub's scripting capabilities to override
      episode_title: >-
         { %array_at( captured_episode_title, 1 ) }
 
-There is no single solution to this problem - it will vary case-by-case. See
+There is no single solution to this problem - it will vary case-by-case. See our full
-our full suite of
+suite of :ref:`scripting functions
-:ref:`scripting functions <config_reference/scripting/scripting_functions:Scripting Functions>`
+<config_reference/scripting/scripting_functions:Scripting Functions>` to create your own
-to create your own clever scraping mechanisms.
+clever scraping mechanisms.
 
 There is a bug where...
 -----------------------
@@ -143,33 +160,39 @@ There is a bug where...
 ..ytdl-sub is not downloading
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Run with ``--log-level verbose`` to see all yt-dlp logs, to rule out whether it is a yt-dlp or ytdl-sub issue.
+Run with ``--log-level verbose`` to see all yt-dlp logs, to rule out whether it is a
+yt-dlp or ytdl-sub issue.
 
-Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp issue.
+Any logs showing failed downloads, 403 errors, signs of throttles, etc, are a yt-dlp
-A good strategy is to see if your same issue has been reported in
+issue.  A good strategy is to see if your same issue has been reported in `yt-dlp's
-`yt-dlp's GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is a comment including
+GitHub issues <https://github.com/yt-dlp/yt-dlp/issues>`_, and search to see if there is
-a fix or workaround.
+a comment including a fix or workaround.
 
-If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a
+If it looks like a ytdl-sub issue, run with ``--log-level debug`` and make a `GitHub
-`GitHub issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_
+issue in ytdl-sub <https://github.com/jmbannon/ytdl-sub/issues>`_ containing these logs
-containing these logs and other relevant info.
+and other relevant info.
 
 ...date_range is not downloading older videos after I changed the range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Your preset most likely has ``break_on_existing`` set to True, which will stop downloading additional metadata/videos if the video exists in your download archive. Set the following in your config to skip downloading videos that exist instead of stopping altogether.
+Your preset most likely has ``break_on_existing`` set to True, which will stop
+downloading additional metadata/videos if the video exists in your download archive. Set
+the following in your config to skip downloading videos that exist instead of stopping
+altogether.
 
 .. code-block:: yaml
 
   ytdl_options:
     break_on_existing: False
 
-After you download your new date_range duration, re-enable ``break_on_existing`` to speed up successive downloads.
+After you download your new date_range duration, re-enable ``break_on_existing`` to
+speed up successive downloads.
 
 ...it is downloading non-English title and description metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Most likely the video has a non-English language set to its 'native' language. You can tell yt-dlp to explicitly download English metadata using.
+Most likely the video has a non-English language set to its 'native' language. You can
+tell yt-dlp to explicitly download English metadata using.
 
 .. code-block:: yaml
 
@@ -185,7 +208,9 @@ Most likely the video has a non-English language set to its 'native' language. Y
 1. Set the following for your ytdl-sub library that has been added to Plex.
 
 .. figure:: ../../images/plex_scanner_agent.png
-  :alt: The Plex library editor, under the advanced settings, showing the required options for Plex to show the TV shows correctly.
+  :alt:
+     The Plex library editor, under the advanced settings, showing the required options
+     for Plex to show the TV shows correctly.
 
 - **Scanner:** Plex Series Scanner
 - **Agent:** Personal Media shows
@@ -193,7 +218,10 @@ Most likely the video has a non-English language set to its 'native' language. Y
 - **Episode sorting:** Library default
 - **YES** Enable video preview thumbnails
 
-2. Under **Settings** > **Agents**, confirm Plex Personal Media Shows/Movies scanner has **Local Media Assets** enabled.
+2. Under **Settings** > **Agents**, confirm Plex Personal Media Shows/Movies scanner has
+   **Local Media Assets** enabled.
 
 .. figure:: ../../images/plex_agent_sources.png
-  :alt: The Plex Agents settings page has Local Media Assets enabled for Personal Media Shows and Movies tabs.
+  :alt:
+     The Plex Agents settings page has Local Media Assets enabled for Personal Media
+     Shows and Movies tabs.

docs/source/guides/development/index.rst

@@ -1,8 +1,10 @@
 Development and Contributing
 ============================
 
+
 Requirements
 ------------
+
 - python >= 3.10
 - ffmpeg/ffprobe 4.4.5 (test checksums rely on this version)
 - make
@@ -20,15 +22,18 @@ Local Install
 
         pip install -e .\[test,lint,docs\]
 
+
 Linter
 ------
-All source code contributed must be formatted to our linter specification.
+
-Run the following to auto-format and check for any issues with your code:
+All source code contributed must be formatted to our linter specification.  Run the
+following to auto-format and check for any issues with your code:
 
 .. code-block:: shell
 
    make lint
 
+
 Adding Documentation
 --------------------
 
@@ -36,12 +41,14 @@ Docs can be found in ``ytdl-sub/docs/source/``, and are built using the command:
 
 
 .. code-block:: shell
-   :caption: Viewable at http://localhost:63342/ytdl-sub/docs/build/html/index.html once built
+   :caption:
+      Viewable at http://localhost:63342/ytdl-sub/docs/build/html/index.html once built
 
    make docs
 
-Some of the documentation is built using doc-strings from the python source code. The above
+Some of the documentation is built using doc-strings from the python source code. The
-command will rebuild those as well.
+above command will rebuild those as well.
+
 
 Testing
 -------
@@ -55,26 +62,31 @@ If integration tests are failing, ensure...
 - you are developing on Linux or Mac (have not tested windows yet)
 - your local ``ytdl-sub`` dependencies are up-to-date
 
+
 IDE Setup
 ---------
-PyCharm is our preferred IDE. The codebase is simple enough to where it's not required, but
+
-is highly recommended.
+PyCharm is our preferred IDE. The codebase is simple enough to where it's not required,
+but is highly recommended.
 
 TODO: screenshots of configuration
 
+
 Debugging
 ---------
 
 Debug Logs
-^^^^^^^^^^^^^^^
+^^^^^^^^^^
+
 Run with ``--log-level debug`` to show all debug logs when running ytdl-sub.
 
 
 Reproducing a Failing Subscription
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction
+
-when using ``--log-level debug``. This can be copy-pasted into the file
+Subscriptions will dump their entire *compiled* yaml at the beginning of exeuction when
+using ``--log-level debug``. This can be copy-pasted into the file
 ``resources/file_fixtures/repro.yaml``.
 
-Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro``
+Running the test ``e2e.test_debug_repro.TestReproduce.test_debug_log_repro`` will fully
-will fully reproduce that subscription in order to debug it.
+reproduce that subscription in order to debug it.

docs/source/guides/getting_started/automating_downloads.rst

@@ -9,6 +9,7 @@ Automating Downloads
 
 .. _cron scheduling syntax: https://crontab.guru/#0_*/6_*_*_*
 
+
 .. _docker-unraid-setup:
 
 Docker and Unraid
@@ -26,11 +27,13 @@ ENV variables to your docker setup.
         - CRON_RUN_ON_START=false
 
 
-- ``CRON_SCHEDULE`` follows the standard `cron scheduling syntax`_. The above value will run the script once every 6 hours.
+- ``CRON_SCHEDULE`` follows the standard `cron scheduling syntax`_. The above value will
-- ``CRON_RUN_ON_START`` toggles whether to run your cron script on container start in addition to the cron schedule.
+  run the script once every 6 hours.
+- ``CRON_RUN_ON_START`` toggles whether to run your cron script on container start in
+  addition to the cron schedule.
 
-The cron script will reside in the main directory with the file name ``cron``.
+The cron script will reside in the main directory with the file name ``cron``.  Cron
-Cron logs should show when viewing the Docker logs.
+logs should show when viewing the Docker logs.
 
 
 .. _linux-setup:
@@ -45,13 +48,13 @@ Must configure crontab manually, like so:
   0     */6     *       *       *       /config/run_cron
 
 
-
-
 .. _windows-setup:
 
 Windows
 -------
-To be tested (please contact code owner or join the discord server if you can test this out for us)
+
+To be tested (please contact code owner or join the discord server if you can test this
+out for us)
 
 .. code-block:: powershell
 

docs/source/guides/getting_started/first_config.rst

@@ -3,10 +3,11 @@ Basic Configuration
 
 A configuration file serves two purposes:
 
-1. Set advanced functionality that is not specifiable in a subscription file, such as working directory location. These
+1. Set advanced functionality that is not specifiable in a subscription file, such as
-   are set underneath ``configuration``.
+   working directory location. These are set underneath ``configuration``.
-2. Create custom presets, which can drastically simplify your subscription file. These are defined underneath ``presets``.
+2. Create custom presets, which can drastically simplify your subscription file. These
-   Presets are intended to be applicable and reusable across multiple subscriptions.
+   are defined underneath ``presets``.  Presets are intended to be applicable and
+   reusable across multiple subscriptions.
 
 Below is a common configuration:
 
@@ -43,10 +44,12 @@ Below is a common configuration:
         - "TV Show"
         - "Only Recent"
 
+
 Configuration Section
 ---------------------
 
-The :ref:`configuration <config_reference/config_yaml:Configuration File>` section sets options for ytdl-sub execution.
+The :ref:`configuration <config_reference/config_yaml:Configuration File>` section sets
+options for ytdl-sub execution.
 
 .. code-block:: yaml
   :lineno-start: 1
@@ -54,10 +57,12 @@ The :ref:`configuration <config_reference/config_yaml:Configuration File>` secti
   configuration:
     working_directory: '/mnt/ssd/.ytdl-sub-downloads'
 
+
 Preset Section
 --------------
 
-Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV Show Only Recent``.
+Underneath ``presets``, we define two custom presets with the names ``TV Show`` and ``TV
+Show Only Recent``.
 
 .. code-block:: yaml
 
@@ -69,6 +74,7 @@ Underneath ``presets``, we define two custom presets with the names ``TV Show``
 
 The indentation example above shows how to define multiple presets.
 
+
 Custom Preset Definition
 ------------------------
 
@@ -88,12 +94,15 @@ Before we break down the above ``TV Show`` preset, lets first outline a preset l
 
 Presets can contain three important things:
 
-1. ``preset`` section, which can inherit :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`
+1. ``preset`` section, which can inherit :ref:`prebuilt presets
-   or other presets defined in your config.
+   <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` or other presets
+   defined in your config.
 2. :ref:`Plugin definitions <config_reference/plugins:Plugins>`
-3. :ref:`overrides <config_reference/plugins:overrides>`, which can override inherited preset variables
+3. :ref:`overrides <config_reference/plugins:overrides>`, which can override inherited
+   preset variables
 
-Presets do not have to define all of these, as we'll see in the ``TV Show Only Recent`` preset.
+Presets do not have to define all of these, as we'll see in the ``TV Show Only Recent``
+preset.
 
 Inheriting Presets
 ~~~~~~~~~~~~~~~~~~
@@ -106,14 +115,16 @@ Inheriting Presets
         - "Jellyfin TV Show by Date"
         - "Max 1080p"
 
-The following snippet shows that the ``TV Show`` preset will inherit all properties
+The following snippet shows that the ``TV Show`` preset will inherit all properties of
-of the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order.
+the prebuilt presets ``Jellyfin TV Show by Date`` and ``Max 1080p`` in that order.
 
 Order matters for preset inheritance. Bottom-most presets will override ones above them.
 
-It is highly advisable to use :ref:`prebuilt presets <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as
+It is highly advisable to use :ref:`prebuilt presets
-a starting point for custom preset building, as they do the work of preset building to ensure things show as expected
+<config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` as a starting point
-in their respective media players. Read on to see how to override prebuilt preset specifics such as title.
+for custom preset building, as they do the work of preset building to ensure things show
+as expected in their respective media players. Read on to see how to override prebuilt
+preset specifics such as title.
 
 Defining Plugins
 ~~~~~~~~~~~~~~~~
@@ -134,17 +145,18 @@ Defining Plugins
            min: 10
            max: 36
 
-Our ``TV Show`` sets two plugins, :ref:`throttle_protection <config_reference/plugins:throttle_protection>` and
+Our ``TV Show`` sets two plugins, :ref:`throttle_protection
-:ref:`embed_thumbnail <config_reference/plugins:embed_thumbnail>`. Each plugin's documentation shows the respective
+<config_reference/plugins:throttle_protection>` and :ref:`embed_thumbnail
-fields that they support.
+<config_reference/plugins:embed_thumbnail>`. Each plugin's documentation shows the
+respective fields that they support.
 
-If an inherited preset defines the same plugin, the custom preset will use 'merge-and-append' strategy to
+If an inherited preset defines the same plugin, the custom preset will use
-combine their definitions. What this means is:
+'merge-and-append' strategy to combine their definitions. What this means is:
-
-1. If the field is a map (i.e. has sub-params like ``sleep_per_download_s`` above) or array, it will try to merge them
-2. If both the inherited preset and custom preset set the same exact field and value (i.e. ``embed_thumbnail``)
-   the custom preset will overwrite it
 
+1. If the field is a map (i.e. has sub-params like ``sleep_per_download_s`` above) or
+   array, it will try to merge them
+2. If both the inherited preset and custom preset set the same exact field and value
+   (i.e. ``embed_thumbnail``) the custom preset will overwrite it
 
 Setting Override Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -155,27 +167,31 @@ Setting Override Variables
       overrides:
         tv_show_directory: "/ytdl_sub_tv_shows"
 
-All override variables reside underneath the :ref:`overrides <config_reference/plugins:overrides>` section.
+All override variables reside underneath the :ref:`overrides
+<config_reference/plugins:overrides>` section.
 
-It is important to remember that individual subscriptions can override specific override variables.
+It is important to remember that individual subscriptions can override specific override
-When defining variables in a preset, it is best practice to define them with the intention that
+variables.  When defining variables in a preset, it is best practice to define them with
+the intention that
 
 1. All subscriptions will use its value them
-2. Use them as placeholders to perform other logic, then have subscriptions or child presets
+2. Use them as placeholders to perform other logic, then have subscriptions or child
-   define their specific value
+   presets define their specific value
 
-For simplicity, we'll focus on (1) for now. The above snippet sets the ``tv_show_directory``
+For simplicity, we'll focus on (1) for now. The above snippet sets the
-variable to a file path. This variable name is specific to the prebuilt TV show presets.
+``tv_show_directory`` variable to a file path. This variable name is specific to the
+prebuilt TV show presets.
 
-See the :ref:`prebuilt preset reference <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`
+See the :ref:`prebuilt preset reference
-to see all available variables that are overridable.
+<config_reference/prebuilt_presets/index:Prebuilt Preset Reference>` to see all
+available variables that are overridable.
 
 
 Using Custom Presets in Subscriptions
 --------------------------------------
 
-Subscription files can use custom presets just like any other prebuilt preset.
+Subscription files can use custom presets just like any other prebuilt preset.  Below
-Below shows a complete subscription file using the above two custom presets.
+shows a complete subscription file using the above two custom presets.
 
 .. code-block:: yaml
 
@@ -193,11 +209,12 @@ Below shows a complete subscription file using the above two custom presets.
 Notice how we do not need to define ``tv_show_directory`` in the ``__preset__`` section
 like in prior examples. This is because our custom presets do the work of defining it.
 
+
 Reference Custom Config in the CLI
 ----------------------------------
 
-Be sure to tell ytdl-sub to use your config by using the argument
+Be sure to tell ytdl-sub to use your config by using the argument ``--config
-``--config /path/to/config.yaml``.
+/path/to/config.yaml``.
 
-If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``, it will
+If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``,
-use it by default.
+it will use it by default.

docs/source/guides/getting_started/first_download.rst

@@ -2,11 +2,13 @@ Initial Download
 ================
 
 Once you have a ``subscriptions.yaml`` file created, you can perform your first
-download. Access ``ytdl-sub``, navigate to the directory containing your ``subscriptions.yaml``
+download. Access ``ytdl-sub``, navigate to the directory containing your
-file.
+``subscriptions.yaml`` file.
+
 
 Dry Run
 -------
+
 Performing a dry run is important when applying any change to your subscriptions to
 ensure output looks as expected. Dry runs will pull metadata to *simulate* a download
 without actually downloading the media file.
@@ -15,11 +17,12 @@ without actually downloading the media file.
 
   ytdl-sub --dry-run sub subscriptions.yaml
 
+
 Faster Iteration Cycle
 ----------------------
-Testing subscriptions can take quite some time to perform a full download.
+
-This can be speed up by applying an override via command-line to set max number
+Testing subscriptions can take quite some time to perform a full download.  This can be
-of downloads.
+speed up by applying an override via command-line to set max number of downloads.
 
 .. code-block:: shell
 
@@ -33,17 +36,20 @@ subscriptions can be dry ran using a match.
 
   ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' --match PBS
 
+
 Downloading
 -----------
-Once the subscriptions file is validated, a download can be performed by omitting the dry run argument.
+
+Once the subscriptions file is validated, a download can be performed by omitting the
+dry run argument.
 
 .. code-block:: shell
 
   ytdl-sub sub subscriptions.yaml
 
-Multiple subscription file names can be provided to perform a download on all of them. A single file
+Multiple subscription file names can be provided to perform a download on all of them. A
-named ``subscriptions.yaml`` does not require a file name specification since it will
+single file named ``subscriptions.yaml`` does not require a file name specification
-look for that file name by default, making the following command valid.
+since it will look for that file name by default, making the following command valid.
 
 .. code-block:: shell
 

docs/source/guides/getting_started/first_sub.rst

@@ -42,17 +42,18 @@ Let's break this down:
       music_directory: "/music"
 
 
-The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is where we
+The first :ref:`__preset__ <config_reference/subscription_yaml:File Preset>` section is
-can set modifications that apply to every subscription in this file.
+where we can set modifications that apply to every subscription in this file.
 
-This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>` variables,
+This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>`
-which are used by the presets below.
+variables, which are used by the presets below.
 
 .. note::
-  It is tempting to put any override underneath ``overrides``. Keep in mind that this section
-  is solely for variable defining. Other :ref:`plugins <config_reference/plugins:Plugins>` need to be
-  set at the same indentation level as ``overrides``, not within it.
 
+  It is tempting to put any override underneath ``overrides``. Keep in mind that this
+  section is solely for variable defining. Other :ref:`plugins
+  <config_reference/plugins:Plugins>` need to be set at the same indentation level as
+  ``overrides``, not within it.
 
 -------------------------------------
 
@@ -61,11 +62,11 @@ which are used by the presets below.
 
   Jellyfin TV Show by Date:
 
-On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a
+On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a :ref:`prebuilt
-:ref:`prebuilt preset <prebuilt_presets/index:prebuilt presets>` that configures
+preset <prebuilt_presets/index:prebuilt presets>` that configures subscriptions to look
-subscriptions to look like TV shows in the Jellyfin media player (can be changed to
+like TV shows in the Jellyfin media player (can be changed to one of the presets
-one of the presets outlined in the comment above). Setting it as a YAML key implies that all
+outlined in the comment above). Setting it as a YAML key implies that all subscriptions
-subscriptions underneath it will *inherit* this preset.
+underneath it will *inherit* this preset.
 
 This preset expects the variable ``tv_show_directory`` to be set, which we do above.
 
@@ -77,14 +78,14 @@ This preset expects the variable ``tv_show_directory`` to be set, which we do ab
   Jellyfin TV Show by Date:
     = Documentaries:
 
-Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are
+Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means
-setting the genre. This value will get written to the respective metadata tags for both TV show
+we are setting the genre. This value will get written to the respective metadata tags
-and music presets.
+for both TV show and music presets.
 
-Behind the scenes, this sets the override variable ``subscription_indent_1``. Further documentation
+Behind the scenes, this sets the override variable ``subscription_indent_1``. Further
-can be found here for
+documentation can be found here for :ref:`subscription syntax
-:ref:`subscription syntax <config_reference/subscription_yaml:Subscription File>` and
+<config_reference/subscription_yaml:Subscription File>` and :ref:`subscription variables
-:ref:`subscription variables <config_reference/scripting/static_variables:Subscription Variables>`.
+<config_reference/scripting/static_variables:Subscription Variables>`.
 
 -------------------------------------
 
@@ -95,12 +96,12 @@ can be found here for
     = Documentaries:
       "NOVA PBS": "https://www.youtube.com/@novapbs"
 
-Line 13 is where we define our first subscription. We set the subscription name to ``NOVA PBS``,
+Line 13 is where we define our first subscription. We set the subscription name to
-and the subscription value to ``https://www.youtube.com/@novapbs``.
+``NOVA PBS``, and the subscription value to ``https://www.youtube.com/@novapbs``.
 
-To see how presets ingest subscription definitions, refer to the
+To see how presets ingest subscription definitions, refer to the :ref:`preset references
-:ref:`preset references <config_reference/prebuilt_presets/tv_show:TV Show>`,
+<config_reference/prebuilt_presets/tv_show:TV Show>`, we can see that
-we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable.
+``{subscription_name}`` is used to set the ``tv_show_name`` variable.
 
 -------------------------------------
 
@@ -114,13 +115,14 @@ we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` vari
     = Kids | = TV-Y:
       "Jake Trains": "https://www.youtube.com/@JakeTrains"
 
-Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``= Documentaries``.
+Line 15 underneath ``Jellyfin TV Show by Date``, but at the same level as ``=
-This means we'll inherit the TV show preset, but not the documentaries indent variable. We instead
+Documentaries``.  This means we'll inherit the TV show preset, but not the documentaries
-set the indent variables to ``= Kids | = TV-Y``. This sets two indent variables. We can set
+indent variable. We instead set the indent variables to ``= Kids | = TV-Y``. This sets
-multiple presets and/or indent variables on the same key by using ``|`` as a separator.
+two indent variables. We can set multiple presets and/or indent variables on the same
+key by using ``|`` as a separator.
 
-Referring to the
+Referring to the :ref:`TV show preset reference
-:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`, the first
+<config_reference/prebuilt_presets/tv_show:TV Show>`, the first two indent variables map
-two indent variables map to the TV show genre and TV show content rating.
+to the TV show genre and TV show content rating.
 
 The above info should be enough to understand the rest of the subscription file.

docs/source/guides/getting_started/index.rst

@@ -1,6 +1,7 @@
 Getting Started
 ===============
 
+
 Prerequisite Knowledge
 ----------------------
 
@@ -29,13 +30,14 @@ how ``ytdl-sub`` works, how it "thinks". So before you start configuring ``ytdl-
 .. _`YAML text files`: http://thomasloven.com/blog/2018/08/YAML-For-Nonprogrammers/
 
 
+
 Architecture
 ------------
 
 For most users, ``ytdl-sub`` works as follows:
 
 Subscriptions use presets
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Run ``$ ytdl-sub sub`` to read :doc:`a subscription file <./first_sub>` that defines
 what subscriptions to download and place into your media library. Each subscription
@@ -43,7 +45,7 @@ selects which :doc:`presets <../../prebuilt_presets/index>` to apply. Those pres
 configure how each subscription is downloaded and placed in the media library.
 
 Presets configure plugins
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :doc:`A preset <../../prebuilt_presets/index>` is effectively a set of plugin
 configurations. Specifically, a preset consists of:
@@ -58,7 +60,7 @@ the same keys for a plugin that one of its base plugins configures, the preset
 configuration overrides the base presets.
 
 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
@@ -67,18 +69,18 @@ metadata for those media, and how to place the resulting files into your media l
 and more.
 
 Presets and subscriptions accept overrides
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Presets accept override keys and values and the preset uses those overrides to modify
 their plugin configurations. Similarly, individual subscriptions can supply overrides of
 their presets for just that subscription.
 
 Subscriptions are grouped by indentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Most subscriptions have more in common with each other than not. Thus, defining the presets
+Most subscriptions have more in common with each other than not. Thus, defining the
-and overrides for each subscription would result in mostly repetition and would multiply
+presets and overrides for each subscription would result in mostly repetition and would
-the burden of management for the user. The more subscriptions the more work.
+multiply the burden of management for the user. The more subscriptions the more work.
 
 To avoid this redundant work, and so that the subscription configurations describe the
 intent of the user, subscriptions are nested/indented under parent/ancestor keys that
@@ -96,14 +98,14 @@ Finally, ancestor keys may use the ``... | ...`` special character to combine mu
 presets and/or genres for the descendant subscriptions beneath.
 
 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
 :doc:`../../prebuilt_presets/index` provided by ``ytdl-sub``.
 
 Caveats
-^^^^^^^
+~~~~~~~
 
 Some of these descriptions are not technically complete. For example, a subscription may
 use no preset at all and will just run ``yt-dlp`` without any customization or post
@@ -118,8 +120,10 @@ is accurate and representative.
 
 Ready to Start?
 ---------------
-Now that you've completed your install of ``ytdl-sub``, it's time to get started.
+
-It is recommended to go through the below sections in order to fully grasp ytdl-sub.
+Now that you've completed your install of ``ytdl-sub``, it's time to get started.  It is
+recommended to go through the below sections in order to fully grasp ytdl-sub.
+
 
 .. toctree::
   :maxdepth: 2

docs/source/guides/install/agnostic.rst

@@ -2,13 +2,15 @@
 Environment Agnostic
 ====================
 
-The PIP install method is not recommended; use of this method may cause unintended requirement conflicts if you have other locally installed apps that depend on ffmpeg.
+The PIP install method is not recommended; use of this method may cause unintended
+requirement conflicts if you have other locally installed apps that depend on ffmpeg.
+
 
 PIP Install
 --------------
-You can install our
+
-`PyPI package <https://pypi.org/project/ytdl-sub/>`_.
+You can install our `PyPI package <https://pypi.org/project/ytdl-sub/>`_.  Both ffmpeg
-Both ffmpeg and Python 3.10 or greater are required.
+and Python 3.10 or greater are required.
 
 .. code-block:: bash
 
@@ -17,10 +19,13 @@ Both ffmpeg and Python 3.10 or greater are required.
 Install for Development
 =======================
 
-These environment-agnostic methods of installing ``ytdl-sub`` are meant for local development of ``ytdl-sub``. If you want to contribute your changes, please read :doc:`/guides/development/index`.
+These environment-agnostic methods of installing ``ytdl-sub`` are meant for local
+development of ``ytdl-sub``. If you want to contribute your changes, please read
+:doc:`/guides/development/index`.
 
 Local Install
 --------------
+
 With a Python 3.10 virtual environment, you can clone and install the repo.
 
 .. code-block:: bash
@@ -32,12 +37,13 @@ With a Python 3.10 virtual environment, you can clone and install the repo.
 
 Local Docker Build
 -------------------
-Run ``make docker`` in the root directory of this repo to build the image. This
+
-will build the python wheel and install it in the Dockerfile.
+Run ``make docker`` in the root directory of this repo to build the image. This will
+build the python wheel and install it in the Dockerfile.
 
 .. code-block:: bash
 
   git clone https://github.com/jmbannon/ytdl-sub.git
   cd ytdl-sub
 
-  make docker
+  make docker

docs/source/guides/install/docker.rst

@@ -10,6 +10,7 @@ the recommended way of managing a ``ytdl-sub`` docker container.  See :ref:`Auto
 Downloads <guides/getting_started/automating_downloads:docker and unraid>` for how to
 automate running ``ytdl-sub`` in a container running either variant.
 
+
 GUI Image
 ---------
 
@@ -21,6 +22,7 @@ and other details. Once running, open `the web UI`_ to edit the `configuration`_
 
 .. _`the web UI`: http://localhost:8443
 
+
 Headless Image
 --------------
 
@@ -36,6 +38,7 @@ For example::
 
   $ docker compose run --rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub" ytdl-sub sub
 
+
 Install with Docker Compose
 ---------------------------
 
@@ -84,6 +87,7 @@ directory such as:
        #       devices:
        #         - capabilities: ["gpu"]
 
+
 Docker CLI
 ----------
 
@@ -109,6 +113,7 @@ host. The following command is for the gui image:
 See `the Docker reference <https://docs.docker.com/engine/reference/run/>`_ for further
 details.
 
+
 Configuration
 -------------
 

docs/source/guides/install/index.rst

@@ -1,5 +1,6 @@
 Install by Platform
 ===================
+
 ``ytdl-sub`` can be installed on the following platforms.
 
 All installations require a 64-bit CPU. 32-bit is not supported.
@@ -8,7 +9,8 @@ All installations require a 64-bit CPU. 32-bit is not supported.
 
   .. tip::
     
-    The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers </guides/install/docker>`.
+    The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers
+    </guides/install/docker>`.
 
 :doc:`/guides/install/docker`
 
@@ -20,9 +22,8 @@ All installations require a 64-bit CPU. 32-bit is not supported.
 
 :doc:`/guides/install/agnostic`
 
-
+Once you've completed your installation, please refer to the
-
+:doc:`../getting_started/index` guide for next steps
-Once you've completed your installation, please refer to the :doc:`../getting_started/index` guide for next steps
 
 .. toctree::
   :hidden:

docs/source/guides/install/linux.rst

@@ -2,8 +2,8 @@
 Linux
 =====
 
-``ytdl-sub`` should be installable using any Linux package manager, and requires ffmpeg to be installed.
+``ytdl-sub`` should be installable using any Linux package manager, and requires ffmpeg
-
+to be installed.
 
 .. tab-set:: 
 
@@ -15,7 +15,8 @@ Linux
       chmod +x ytdl-sub
       ./ytdl-sub -h
 
-    You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to date:
+    You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to
+    date:
 
     .. code-block:: bash
 
@@ -36,7 +37,8 @@ Linux
       chmod +x ytdl-sub
       ./ytdl-sub -h
 
-    You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to date:
+    You can also install using yt-dlp's ffmpeg builds. This ensures your ffmpeg is up to
+    date:
 
     .. code-block:: bash
 

docs/source/guides/install/unraid.rst

@@ -1,16 +1,29 @@
+======
 Unraid
---------------
+======
-You can install our :unraid:`unraid community apps <community/apps?q=ytdl-sub#r>` through the  `Unraid Community Apps plugin <https://unraid.net/community/apps>`_.
 
+You can install our :unraid:`unraid community apps <community/apps?q=ytdl-sub#r>`
+through the `Unraid Community Apps plugin <https://unraid.net/community/apps>`_.
 
-If you installed the ``ytdl-sub-gui`` app, the code-server will be running at http://localhost:8443 (replace ``localhost`` with the IP of the computer running Unraid if you aren't trying to access ``ytdl-sub`` on that computer). Open this page in a browser to access and interact with ``ytdl-sub``. 
+If you installed the ``ytdl-sub-gui`` app, the code-server will be running at
+http://localhost:8443 (replace ``localhost`` with the IP of the computer running Unraid
+if you aren't trying to access ``ytdl-sub`` on that computer). Open this page in a
+browser to access and interact with ``ytdl-sub``.
 
-If you installed the ``ytdl-sub`` app (headless), open the normal app-specific console to access and interact with ``ytdl-sub``. Once open, you must first run ``su abc -s /bin/bash`` to change to the non-root user. You can confirm that this command worked by running ``whoami`` and verifying that the result is ``abc``.
+If you installed the ``ytdl-sub`` app (headless), open the normal app-specific console
+to access and interact with ``ytdl-sub``. Once open, you must first run ``su abc -s
+/bin/bash`` to change to the non-root user. You can confirm that this command worked by
+running ``whoami`` and verifying that the result is ``abc``.
 
+.. warning::
 
-.. warning:: 
+   If you use the below option to access the ``ytdl-sub`` console, be sure to run ``su
+   abc -s /bin/bash`` first thing. You can confirm that this command worked by running
+   ``whoami`` and verifying that the result is ``abc``. Do **NOT** run ``ytdl-sub`` as
+   the root user! Running as root will set the owner of all modified files to root,
+   which prevents most media managers and players from accessing the files.
 
-  If you use the below option to access the ``ytdl-sub`` console, be sure to run ``su abc -s /bin/bash`` first thing. You can confirm that this command worked by running ``whoami`` and verifying that the result is ``abc``. Do **NOT** run ``ytdl-sub`` as the root user! Running as root will set the owner of all modified files to root, which prevents most media managers and players from accessing the files.
+   .. figure:: ../../../images/unraid_badconsole.png
-
+     :alt:
-  .. figure:: ../../../images/unraid_badconsole.png
+	The Unraid community app plugin GUI, with an arrow pointing at the "Console"
-    :alt: The Unraid community app plugin GUI, with an arrow pointing at the "Console" option in the dropdown after selecting ytdl-sub-gui
+	option in the dropdown after selecting ytdl-sub-gui

docs/source/guides/install/windows.rst

@@ -1,5 +1,7 @@
+=======
 Windows
---------------
+=======
+
 From powershell, run:
 
 .. code-block:: powershell
@@ -12,4 +14,4 @@ From powershell, run:
 
   # Download ytdl-sub
   curl.exe -L -o ytdl-sub.exe https://github.com/jmbannon/ytdl-sub/releases/latest/download/ytdl-sub.exe
-  ytdl-sub.exe -h
+  ytdl-sub.exe -h

docs/source/prebuilt_presets/helpers.rst

@@ -6,11 +6,13 @@ Helper Presets
 
    See how to apply helper presets :doc:`here </prebuilt_presets/index>`
 
+
 Only Recent
 -----------
 
-To only download a recent number of videos, apply the ``Only Recent`` preset. Once a video's
+To only download a recent number of videos, apply the ``Only Recent`` preset. Once a
-upload date is outside of the range, or you hit max files, older videos will be deleted automatically.
+video's upload date is outside of the range, or you hit max files, older videos will be
+deleted automatically.
 
 .. code-block:: yaml
 
@@ -31,9 +33,12 @@ To prevent deletion of files, use the preset ``Only Recent Archive`` instead.
 Filter Keywords
 ---------------
 
-``Filter Keywords`` can include or exclude media with any of the listed keywords. Both keywords and title/description are lower-cased before filtering.
+``Filter Keywords`` can include or exclude media with any of the listed keywords. Both
+keywords and title/description are lower-cased before filtering.
 
-Default behavior for Keyword evaluation is ANY, meaning the filter will succeed if any of the keywords are present. This can be set to ANY or ALL using the respective ``_eval`` variable.
+Default behavior for Keyword evaluation is ANY, meaning the filter will succeed if any
+of the keywords are present. This can be set to ANY or ALL using the respective
+``_eval`` variable.
 
 Supports the following override variables:
 
@@ -71,6 +76,7 @@ Supports the following override variables:
               - "maple leafs"
               - "highlights"
 
+
 Filter Duration
 ---------------
 
@@ -100,17 +106,19 @@ Supports the following override variables:
             url: "https://www.youtube.com/@NHL"
             filter_duration_max_s: 180  # Only get highlight videos less than 3m long
 
+
 Chunk Downloads
 ---------------
 
-If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's metadata from newest to oldest before
+If you are archiving a large channel, ``ytdl-sub`` will try pulling each video's
-starting any downloads. It is a long process and not ideal. A better method is to chunk the process by using the
+metadata from newest to oldest before starting any downloads. It is a long process and
-following preset:
+not ideal. A better method is to chunk the process by using the following preset:
 
 ``Chunk Downloads``
 
-It will download videos starting from the oldest one, and only download 20 at a time by default. You can
+It will download videos starting from the oldest one, and only download 20 at a time by
-change this number by setting the override variable ``chunk_max_downloads``.
+default. You can change this number by setting the override variable
+``chunk_max_downloads``.
 
 .. code-block:: yaml
 
@@ -129,5 +137,6 @@ change this number by setting the override variable ``chunk_max_downloads``.
      = Documentaries:
        "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
 
-Once the entire channel is downloaded, remove the usage of this preset. It will then pull metadata from newest to
+Once the entire channel is downloaded, remove the usage of this preset. It will then
-oldest again, and stop once it reaches a video that has already been downloaded.
+pull metadata from newest to oldest again, and stop once it reaches a video that has
+already been downloaded.

docs/source/prebuilt_presets/index.rst

@@ -7,11 +7,13 @@ media in various players.
 
 .. hint::
 
-   Apply multiple presets to your subscriptions using pipes. Pipes can define multiple presets and values
+   Apply multiple presets to your subscriptions using pipes. Pipes can define multiple
-   on the same line to apply to all subscriptions nested below them.
+   presets and values on the same line to apply to all subscriptions nested below them.
 
    .. code-block:: yaml
-     :caption: Applies Max Video Quality preset to all TV shows, and Chunk Downloads preset to some
+     :caption:
+	Applies Max Video Quality preset to all TV shows, and Chunk Downloads preset to
+	some
 
      Plex TV Show by Date | Max Video Quality:
 
@@ -22,9 +24,8 @@ media in various players.
        = Documentaries:
          "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
 
-
+For advanced users, you can review the prebuilt preset definitions :doc:`here
-For advanced users, you can review the prebuilt preset
+</config_reference/prebuilt_presets/index>`.
-definitions :doc:`here </config_reference/prebuilt_presets/index>`.
 
 .. toctree:: 
   :titlesonly:
@@ -33,4 +34,4 @@ definitions :doc:`here </config_reference/prebuilt_presets/index>`.
   music
   music_videos
   media_quality
-  helpers
+  helpers

docs/source/prebuilt_presets/media_quality.rst

@@ -6,8 +6,10 @@ Media Quality Presets
 
    See how to apply media quality presets :doc:`here </prebuilt_presets/index>`
 
+
 Video
 -----
+
 The following presets set video quality specifications to yt-dlp.
 
 - ``Max Video Quality``
@@ -17,10 +19,12 @@ The following presets set video quality specifications to yt-dlp.
 - ``Max 720p``
 - ``Max 480p``
 
+
 Audio
 -----
-The following presets set audio quality specifications to yt-dlp.
+
-These assume you are only extracting audio (no video).
+The following presets set audio quality specifications to yt-dlp.  These assume you are
+only extracting audio (no video).
 
 - ``Max Audio Quality``, format is determined by the source
 - ``Max MP3 Quality``

docs/source/prebuilt_presets/music.rst

@@ -2,21 +2,21 @@
 Music Presets
 =============
 
-Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite
+Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite of
-of various presets for handling some of the most popular forms of uploaded music
+various presets for handling some of the most popular forms of uploaded music content.
-content.
 
 .. hint::
 
-  The subscription *value* (denoted by =) will set the genre tag for all music scraped under its key
+  The subscription *value* (denoted by =) will set the genre tag for all music scraped
-  for all music presets.
+  under its key for all music presets.
 
 
 YouTube Releases
 ----------------
+
 Many artists, especially those auto-uploaded as ``Topics`` in YouTube have a section on
-their channel named "Releases", or "Albums and Singles". The ``YouTube Releases`` preset aims to
+their channel named "Releases", or "Albums and Singles". The ``YouTube Releases`` preset
-scrape this *playlist of playlists*.
+aims to scrape this *playlist of playlists*.
 
 Playlists are recognized as the album, and videos within it are tracks.
 
@@ -26,8 +26,8 @@ Playlists are recognized as the album, and videos within it are tracks.
      = Jazz:  # Sets genre tag to "Jazz"
        "Thelonious Monk": "https://www.youtube.com/@officialtheloniousmonk/releases"
 
-If you are only interested in a subset of albums, you can provide their playlists as separate values in the form
+If you are only interested in a subset of albums, you can provide their playlists as
-of an array, like so:
+separate values in the form of an array, like so:
 
 .. code-block:: yaml
 
@@ -37,11 +37,13 @@ of an array, like so:
          - "https://www.youtube.com/playlist?list=OLAK5uy_lcqINwfzkw73TPnAt6MlpB6V0gM9VzQu8"  # Monk on Monk
          - "https://www.youtube.com/playlist?list=OLAK5uy_nhuvjuZOO3yLIWCbQzbiWfyzkGapSIuYw"  # Late Night Thelonious Monk
 
+
 YouTube Full Albums
 -------------------
-In many cases, albums are uploaded to YouTube as a single video, where each track as separated by either
+
-chapters or timestamps in a description. The ``YouTube Full Albums`` preset will take each video and split
+In many cases, albums are uploaded to YouTube as a single video, where each track as
-it by the chapters to form an album.
+separated by either chapters or timestamps in a description. The ``YouTube Full Albums``
+preset will take each video and split it by the chapters to form an album.
 
 Videos are recognized as the album, and chapters within it are tracks.
 
@@ -51,8 +53,8 @@ Videos are recognized as the album, and chapters within it are tracks.
      = Lofi:
        "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"
 
-If you are only interested in a subset of albums, you can provide their video as separate values in the form
+If you are only interested in a subset of albums, you can provide their video as
-of an array, like so:
+separate values in the form of an array, like so:
 
 .. code-block:: yaml
 
@@ -62,11 +64,14 @@ of an array, like so:
          - "https://www.youtube.com/watch?v=m7vBrD7LMLI"  # Zelda & Sleep Ensemble Collection
          - "https://www.youtube.com/watch?v=w0XebCwSpKI"  # Study Buddy ~ video game lofi mix
 
+
 Soundcloud Discography
 ----------------------
-SoundCloud tracks can be uploaded as either a single, part of an album, or a collaboration
+
-with another artist. At this time, ``SoundCloud Discography`` only scrapes singles and albums.
+SoundCloud tracks can be uploaded as either a single, part of an album, or a
-It will attempt to group tracks into albums before falling back to single format.
+collaboration with another artist. At this time, ``SoundCloud Discography`` only scrapes
+singles and albums.  It will attempt to group tracks into albums before falling back to
+single format.
 
 .. code-block:: yaml
 
@@ -77,8 +82,10 @@ It will attempt to group tracks into albums before falling back to single format
        "Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords"
        "Earmake": "https://soundcloud.com/earmake"
 
+
 Bandcamp
 --------
+
 Bandcamp albums and singles can be scraped using the ``Bandcamp`` preset.
 
 .. code-block:: yaml

docs/source/prebuilt_presets/music_videos.rst

@@ -2,4 +2,4 @@
 Music Video Presets
 ===================
 
-WIP
+WIP

docs/source/prebuilt_presets/tv_shows.rst

@@ -2,45 +2,57 @@
 TV Show Presets
 ===============
 
-Player-Specific Presets
-=======================
 
-``ytdl-sub`` provides player-specific versions of certain presets, which apply settings to optimize the downloads for that player.
+Player-Specific Presets
+-----------------------
+
+``ytdl-sub`` provides player-specific versions of certain presets, which apply settings
+to optimize the downloads for that player.
 
 The following actions are taken based on the indicated player:
 
 Kodi
---------
+~~~~
+
 * Everything that the Jellyfin version does
-* Enables ``kodi_safe`` NFOs, replacing 4-byte unicode characters that break kodi with ``□``
+* Enables ``kodi_safe`` NFOs, replacing 4-byte unicode characters that break kodi with
+  ``□``
 
 Jellyfin
---------
+~~~~~~~~
+
 * Places any season-specific poster art in the main show folder
 * Generates NFO tags
 
 Emby
-----
+~~~~
+
 * Places any season-specific poster art in the main show folder
 * Generates NFO tags
 
   * For named seasons, creates a ``season.nfo`` file per season
 
 Plex
---------
+~~~~~~~~
-* :ref:`Special sanitization <config_reference/scripting/entry_variables:title_sanitized_plex>` of numbers so Plex doesn't recognize numbers that are part of the title as the episode number
+
+* :ref:`Special sanitization
+  <config_reference/scripting/entry_variables:title_sanitized_plex>` of numbers so Plex
+  doesn't recognize numbers that are part of the title as the episode number
 * Converts all downloaded videos to the mp4 format
 * Places any season-specific poster art into the season folder
 
 ----------------------------------------------
 
-TV Show by Date
-===============
 
-TV Show by Date will organize something like a YouTube channel or playlist into a tv show, where seasons and episodes are organized using upload date.
+TV Show by Date
+---------------
+
+TV Show by Date will organize something like a YouTube channel or playlist into a tv
+show, where seasons and episodes are organized using upload date.
 
 Example
--------
+~~~~~~~
+
 Must define ``tv_show_directory``. Available presets:
 
 * ``Kodi TV Show by Date``
@@ -74,9 +86,10 @@ Must define ``tv_show_directory``. Available presets:
          - "https://www.youtube.com/@rickbeato240"
 
 Advanced Usage
---------------
+~~~~~~~~~~~~~~
 
-If you prefer a different season/episode organization method, you can set the following override variables.
+If you prefer a different season/episode organization method, you can set the following
+override variables.
 
 .. code-block:: yaml
 
@@ -95,12 +108,11 @@ Or for a specific preset
           tv_show_by_date_season_ordering: "upload-year-month"
           tv_show_by_date_episode_ordering: "upload-day"
 
-The following are supported. Be sure the combined season + episode ordering
+The following are supported. Be sure the combined season + episode ordering include the
-include the year, month, day, i.e. upload-year + upload-month-day.
+year, month, day, i.e. upload-year + upload-month-day.
-
 
 Season Ordering
-~~~~~~~~~~~~~~~
+"""""""""""""""
 
 ``tv_show_by_date_season_ordering`` supports one of the following:
 
@@ -109,23 +121,24 @@ Season Ordering
 * ``release-year``
 * ``release-year-month``
 
-
 Episode Ordering
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""
 
 ``tv_show_by_date_episode_ordering`` supports one of the following:
 
 * ``upload-month-day`` (default)
 * ``upload-month-day-reversed``
 
-  * Reversed means more recent episodes appear at the top of a season by having a lower value.
+  * Reversed means more recent episodes appear at the top of a season by having a lower
+    value.
 * ``upload-day``
 * ``release-day``
 * ``release-month-day``
 * ``release-month-day-reversed``
 * ``download-index``
 
-  * Episodes are numbered by the download order. **NOTE**: this is fetched using the length of the download archive. Do not use if you intend to remove old videos.
+  * Episodes are numbered by the download order. **NOTE**: this is fetched using the
+    length of the download archive. Do not use if you intend to remove old videos.
 
 TV Show by Date presets use the following for defaults:
 
@@ -135,21 +148,21 @@ TV Show by Date presets use the following for defaults:
    tv_show_by_date_episode_ordering: "upload-month-day"
 
 TV Show Collection
-==================
+------------------
 
 TV Show Collections set each URL as its own season. If a video belongs to multiple URLs
-(i.e. a channel and a channel's playlist), the video will only download once and reside in
+(i.e. a channel and a channel's playlist), the video will only download once and reside
-the higher-numbered season.
+in the higher-numbered season.
 
 Two main use cases of a collection are:
-   1. Organize a YouTube channel TV show where Season 1 contains any video
+   1. Organize a YouTube channel TV show where Season 1 contains any video not in a
-      not in a 'season playlist', Season 2 for 'Playlist A', Season 3 for
+      'season playlist', Season 2 for 'Playlist A', Season 3 for 'Playlist B', etc.
-      'Playlist B', etc.
+   2. Organize one or more YouTube channels/playlists, where each season represents a
-   2. Organize one or more YouTube channels/playlists, where each season
+      separate channel/playlist.
-      represents a separate channel/playlist.
 
 Example
--------
+~~~~~~~
+
 Must define ``tv_show_directory``. Available presets:
 
 * ``Kodi TV Show Collection``
@@ -173,9 +186,10 @@ Must define ``tv_show_directory``. Available presets:
          s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W"
 
 Advanced Usage
---------------
+~~~~~~~~~~~~~~
 
-If you prefer a different episode organization method, you can set the following override variables.
+If you prefer a different episode organization method, you can set the following
+override variables.
 
 .. code-block:: yaml
 
@@ -198,9 +212,8 @@ Or for a specific preset
 
 The following are supported.
 
-
 Episode Ordering
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""
 
 ``tv_show_collection_episode_ordering`` supports one of the following:
 
@@ -210,7 +223,8 @@ Episode Ordering
 * ``release-year-month-day-reversed``
 * ``playlist-index``
 
-  * Only use ``playlist-index`` episode formatting for playlists that will be fully downloaded once and never again. Otherwise, indices can change.
+  * Only use ``playlist-index`` episode formatting for playlists that will be fully
+    downloaded once and never again. Otherwise, indices can change.
 * ``playlist-index-reversed``
 
 TV Show Collection presets use upload-year-month-day as the default.

docs/source/usage.rst

@@ -1,5 +1,5 @@
 Usage
-=======
+=====
 
 .. code-block::
 
@@ -7,6 +7,7 @@ Usage
 
 For Windows users, it would be ``ytdl-sub.exe``
 
+
 General Options
 ---------------
 
@@ -28,16 +29,19 @@ General options must be specified before the command (i.e. ``sub``).
   -m MATCH [MATCH ...], --match MATCH [MATCH ...]
                         match subscription names to one or more substrings, and only run those subscriptions
 
+
 Sub Options
 -----------
+
 Download all subscriptions specified in each ``SUBPATH``.
 
 .. code-block::
 
    ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
 
-``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if not provided.
+``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if
-It will use the config specified by ``--config``, or ``config.yaml`` if not provided.
+not provided.  It will use the config specified by ``--config``, or ``config.yaml`` if
+not provided.
 
 .. code-block:: text
   :caption: Additional Options
@@ -47,16 +51,19 @@ It will use the config specified by ``--config``, or ``config.yaml`` if not prov
   -o DL_OVERRIDE, --dl-override DL_OVERRIDE
                         override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
 
+
 Download Options
------------------
+----------------
+
 Download a single subscription in the form of CLI arguments.
 
 .. code-block::
 
   ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]
 
-``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods (``.``) instead
+``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods
-of indents for specifying YAML from the CLI. For example, you can represent this subscription:
+(``.``) instead of indents for specifying YAML from the CLI. For example, you can
+represent this subscription:
 
 .. code-block:: yaml
 
@@ -76,11 +83,13 @@ Using the command:
       --overrides.tv_show_name "Rick A" \
       --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
 
-See how to shorten commands using
+See how to shorten commands using `download aliases
-`download aliases <https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
+<https://ytdl-sub.readthedocs.io/en/latest/config_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
+
 
 View Options
------------------
+------------
+
 .. code-block::
 
    ytdl-sub view [-sc] [URL]
@@ -91,5 +100,4 @@ View Options
   -sc, --split-chapters
                         View source variables after splitting by chapters
 
-
 Preview the source variables for a given URL. Helps when creating new configs.