[DOCS] Add more configuration docs (#916)

docs/source/config_reference/prebuilt_presets/common.rst

@@ -0,0 +1,15 @@
+=======================
+Common
+=======================
+
+.. highlight:: yaml
+
+Media Quality
+-------------
+
+.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml
+
+Only Recent Videos
+------------------
+
+.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml

docs/source/config_reference/prebuilt_presets/helpers_common.rst

@@ -1,7 +0,0 @@
-=======================
-Common Preset Reference
-=======================
-
-.. highlight:: yaml
-
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/common.yaml

docs/source/config_reference/prebuilt_presets/helpers_players.rst

@@ -1,7 +0,0 @@
-========================
-Players Preset Reference
-========================
-
-.. highlight:: yaml
-
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/players.yaml

docs/source/config_reference/prebuilt_presets/helpers_url.rst

@@ -1,7 +0,0 @@
-====================
-URL Preset Reference
-====================
-
-.. highlight:: yaml
-
-.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/helpers/url.yaml

docs/source/config_reference/prebuilt_presets/index.rst

@@ -6,7 +6,7 @@ This section contains the code for the prebuilt presets. If you just want to und
 
 
 
-.. toctree:: 
+.. toctree::
-  helpers_common
+  common
-  helpers_players
+  tv_show
-  helpers_url
+  music

docs/source/config_reference/prebuilt_presets/music.rst

@@ -0,0 +1,9 @@
+=====
+Music
+=====
+
+All audio music based presets inherit from ``_music_base``.
+
+.. highlight:: yaml
+
+.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/music/singles.yaml

docs/source/config_reference/prebuilt_presets/tv_show.rst

@@ -0,0 +1,9 @@
+========================
+TV Show
+========================
+
+All TV show based presets inherit from ``_episode_base``.
+
+.. highlight:: yaml
+
+.. literalinclude:: /../../src/ytdl_sub/prebuilt_presets/tv_show/episode.yaml

docs/source/guides/getting_started/advanced_configuration.rst

@@ -16,6 +16,41 @@ The layout of the ``config.yaml`` file is relatively straightforward:
       plugin1:
         plugin1_option1: value1
 
+This creates a preset named ``preset_name``, which contains the made-up
+:doc:`plugin </config_reference/plugins>` ``plugin1``. Under each plugin are its settings.
+A preset can contain multiple plugins.
 
 Preset Inheritance
 ------------------
+
+You can modularize your presets via preset inheritance. For example,
+
+.. code-block:: yaml
+
+  presets:
+
+    TV Show:
+      presets:
+        - "Jellyfin TV Show by Date"
+
+      overrides:
+        tv_show_directory: "/ytdl_sub_tv_shows"
+
+    TV Show Only Recent:
+      presets:
+        - "TV Show"
+        - "Only Recent"
+
+      overrides:
+        only_recent_date_range: "3weeks"
+
+This creates two presets:
+
+* ``TV Show``
+   * Inherits the :doc:`prebuilt </prebuilt_presets/index>` ``Jellyfin TV Show by Date`` preset
+   * Sets the output tv show directory
+* ``TV Show Only Recent``
+   * Inherits the ``TV Show`` preset made above it and the ``Only Recent`` prebuilt preset
+   * Sets only_recent preset to only keep the last 3 weeks worth of videos
+
+Inheritance makes it easy to extend existing presets to include logic for your specific needs.

docs/source/guides/getting_started/first_config.rst

@@ -9,6 +9,14 @@ Your first configuration will look pretty simple:
   configuration:
     working_directory: '.ytdl-sub-downloads'
 
+  presets:
+    TV Show:
+      preset:
+        - "Jellyfin TV Show by Date"
+        - "Only Recent"
+
+      overrides:
+        tv_show_directory: "/ytdl_sub_tv_shows"
 
 
 The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section <guides/getting_started/index:quick overview of \`\`ytdl-sub\`\`>`

src/ytdl_sub/prebuilt_presets/helpers/download_deletion_options.yaml

@@ -1,18 +1,8 @@
 presets:
 
-  "Only Recent":
+  #############################################################################
-    preset:
+  # Only Recent Archive
-      - "Only Recent Archive"
+  #   Downloads only `date_range` amount of videos (no deletion)
-    # Only fetch videos after today minus date_range
-
-    # Only keep files uploaded after date_range
-    output_options:
-      keep_files_after: "today-{only_recent_date_range}"
-      keep_max_files: "{only_recent_max_files}"
-
-    overrides:
-      only_recent_max_files: 0
-
 
   "Only Recent Archive":
     # Only fetch videos after today minus date_range
@@ -23,9 +13,29 @@ presets:
     overrides:
       date_range: "2months"  # keep for legacy-reasons
       only_recent_date_range: "{date_range}"
-      
 
-  chunk_initial_download:
+  #############################################################################
+  # Only Recent
+  #   Downloads only `date_range` amount of videos and deletes older videos
+  #   that fall out of that range
+
+  "Only Recent":
+    preset:
+      - "Only Recent Archive"
+
+    output_options:
+      keep_files_after: "today-{only_recent_date_range}"
+      keep_max_files: "{only_recent_max_files}"
+
+    overrides:
+      only_recent_max_files: 0
+
+  #############################################################################
+  # Download in Chunks
+  #   Will only download 20 videos per invocation of ytdl-sub, starting
+  #   at the very beginning of the channel
+
+  chunk_initial_download:  # legacy preset name
     ytdl_options:
       max_downloads: 20
       playlistreverse: True

src/ytdl_sub/prebuilt_presets/helpers/media_quality.yaml

@@ -1,5 +1,9 @@
 presets:
 
+  #############################################################################
+  # Best Video Quality
+  #   Gets the best available quality
+
   best_video_quality:
     format: "bestvideo+bestaudio/best"
     ytdl_options:
@@ -9,18 +13,26 @@ presets:
     preset: 
       - best_video_quality
 
+  #############################################################################
+  # Max 2160p
 
   "Max 2160p":
     format: "(bv*[height<=2160]+bestaudio/best[height<=2160])"
     ytdl_options:
       merge_output_format: "mp4"
 
+  #############################################################################
+  # Max 1440p
+
   "Max 1440p":
     format: "(bv*[height<=1440]+bestaudio/best[height<=1440])"
     ytdl_options:
       merge_output_format: "mp4"
 
-  max_1080p:
+  #############################################################################
+  # Max 1080p
+
+  max_1080p:  # legacy name
     format: "(bv*[height<=1080]+bestaudio/best[height<=1080])"
     ytdl_options:
       merge_output_format: "mp4"
@@ -28,12 +40,18 @@ presets:
   "Max 1080p":
     preset:
       - max_1080p
-  
+
+  #############################################################################
+  # Max 720p
+
   "Max 720p":
     format: "(bv*[height<=720]+bestaudio/best[height<=720])"
     ytdl_options:
       merge_output_format: "mp4"
 
+  #############################################################################
+  # Max 480p
+
   "Max 480p":
     format: "(bv*[height<=480]+bestaudio/best[height<=480])"
     ytdl_options: