Presets and touch ups

docs/source/conf.py

@@ -47,9 +47,7 @@ html_theme_options = {
       "type": "url",
     },
   ],
-  "announcement": (
+  "announcement": ("Please excuse our mess as we update these documents"),
-    "Please excuse our mess as we update these documents"
-  ),
   "navigation_depth": 10,
   "show_toc_level": 10,
 }
@@ -61,7 +59,7 @@ html_static_path = ["_static"]
 autosectionlabel_prefix_document = True
 
 suppress_warnings = [
-  'autosectionlabel.*',
+  "autosectionlabel.*",
 ]
 
 extlinks = {
@@ -69,8 +67,8 @@ extlinks = {
   "unraid": ("https://unraid.net/%s", "unraid%s"),
   "lsio": ("https://www.linuxserver.io/%s", "lsio%s"),
   "lsio-gh": ("https://github.com/linuxserver/%s", "%s image"),
-  "ytdl-sub-gh": ("https://github.com/jmbannon/ytdl-sub/%s","src %s"),
+  "ytdl-sub-gh": ("https://github.com/jmbannon/ytdl-sub/%s", "src %s"),
-  }
+}
 
 # -- Options for autodoc ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration

docs/source/config_reference/subscriptions_yaml.rst

@@ -102,7 +102,6 @@ parent preset:
 
 File Preset
 ~~~~~~~~~~~
-NOTE: This is deprecated in favor of using the method in :ref:`config_reference/subscriptions_yaml:beautifying subscriptions`.
 
 You can apply a preset to all subscriptions in the ``subscription.yaml`` file
 by using the file-wide ``__preset__``:

docs/source/guides/getting_started/examples.rst

@@ -1,5 +1,6 @@
+=====================
 Using Example Configs
-^^^^^^^^^^^^^^^^^^^^^^
+=====================
 Copy and paste the examples into local yaml files, modify the
 ``working_directory`` and ``output_directory`` with your desired paths,
 and perform a dry-run using

docs/source/guides/getting_started/first_config.rst

@@ -1,5 +1,5 @@
-Initial Configuration
+Basic Configuration
-=====================
+===================
 
 Your first configuration will look pretty simple:
 
@@ -9,14 +9,6 @@ Your first configuration will look pretty simple:
   configuration:
     working_directory: '.ytdl-sub-downloads'
 
-  presets:
-    "My Favorite YouTube Channels":
-      preset:
-        - "Jellyfin TV Show by Date"
-        - "Only Recent"
-
-      overrides:
-        tv_show_directory: "/tv_shows/youtube"
 
 
 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\`\`>`

docs/source/guides/getting_started/first_sub.rst

@@ -4,10 +4,18 @@ Initial Subscription
 Your first subscription should look similar to the below:
 
 .. code-block:: yaml
+  :linenos:
   
+  __preset__:
+    overrides:
+      tv_show_directory: "/tv_shows"
+
   "My Favorite YouTube Channels":
     "Rick Astley": "https://www.youtube.com/@RickAstleyYT/videos"
 
-The first line in this subscription file is the ``preset``, which provides the "definitions" for the subscription as listed in :doc:`/guides/getting_started/first_config`.
 
-The second line is the actual ``subscription``, named ``Rick Astley``, with a link to a :yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`, in this case a YouTube channel.
+The first three lines in this subscription file define where to save the downloaded files associated with all subscriptions in this file.
+
+The fifth line in this subscription file is the ``preset``, which provides the "definitions" for the subscription as listed in :doc:`/guides/getting_started/first_config`.
+
+The sixth line is the actual ``subscription``, named ``Rick Astley``, with a link to a :yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`, in this case a YouTube channel.

docs/source/guides/getting_started/index.rst

@@ -63,9 +63,11 @@ Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit
 
 :doc:`Step 3: Automating Downloads <automating_downloads>`
 
-:doc:`Step 4: Initial Configuration <first_config>`
+Want to go a step further?
 
-:doc:`Advanced Configuration <advanced_configuration>`
+If you want to use atypical paths or specific configuration options, check out :doc:`Basic Configuration <first_config>`
+
+For tips on creating your own presets when the prebuilt presets aren't cutting it, check out :doc:`Advanced Configuration <advanced_configuration>`
 
 Other docs that may be of use:
 
@@ -78,9 +80,9 @@ Other docs that may be of use:
   :caption: Getting Started Guide
   :maxdepth: 1
 
-  first_config
   first_sub
   first_download
   automating_downloads
+  first_config
   advanced_configuration
   examples

docs/source/prebuilt_presets/index.rst

@@ -1,11 +1,14 @@
-Presets
+================
-=======
+Prebuilt Presets
+================
 
 ``ytdl-sub`` offers a number of built-in presets using best practices for formatting
-media in various players. For advanced users, you can find the prebuilt preset
+media in various players. For advanced users, you can review the prebuilt preset
-definitions :ytdl-sub-gh:`here <tree/8998861b497f692ce17c949f0c4c3530831085b1/src/ytdl_sub/prebuilt_presets>`.
+definitions :doc:`here </config_reference/prebuilt_presets/index>`.
 
 .. toctree:: 
+  :titlesonly:
+  
   helpers
   tv_shows
   music

docs/source/prebuilt_presets/music.rst

@@ -1,3 +1,3 @@
-============
+=============
-Music Prests
+Music Presets
-============
+=============

docs/source/prebuilt_presets/tv_shows.rst

@@ -7,7 +7,7 @@ Player-Specific Presets
 
 ``ytdl-sub`` provides player-specific versions of certain presets, which apply settings to optimize the downloads for that player.
 
-All of these players will have:
+The following actions are taken based on the indicated player:
 
 
 Jellyfin
@@ -26,6 +26,8 @@ Plex
 * Converts all downloaded videos to the mp4 format
 * Places any season-specific poster art into the season folder
 
+----------------------------------------------
+
 Generic Presets
 ===============
 
@@ -34,70 +36,78 @@ There are two main methods for downloading and formatting videos as a TV show.
 TV Show by Date
 ---------------
 
-TV Show by Date will organize something like a YouTube channel or playlist
+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.
-into a tv show, where seasons and episodes are organized using upload date.
 
-Player Presets
+Plug and Play Presets
+~~~~~~~~~~~~~~~~~~~~~
+
+You can use any of these presets in your ``subscriptions.yaml`` as a "One size fits all" solution- they should set all appropriate values. These will organize seasons by year and episodes by month, then day.
+
+Must define ``tv_show_directory``
+
+* ``"Kodi TV Show by Date"``
+* ``"Jellyfin TV Show by Date"``
+* ``"Plex TV Show by Date"``
+
+Advanced Usage
 ~~~~~~~~~~~~~~
 
+If you prefer a different organization method, you can instead apply multiple presets to your subscriptions.
+
+You will need a base of one of the below:
+
 * ``kodi_tv_show_by_date``
 * ``jellyfin_tv_show_by_date``
 * ``plex_tv_show_by_date``
 
-Episode Formatting Presets
+And then add one of these:
-~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ``season_by_year__episode_by_month_day``
 * ``season_by_year_month__episode_by_day``
 * ``season_by_year__episode_by_month_day_reversed``
-   * Episode numbers are reversed, meaning more recent episodes appear at the
+  
-     top of a season by having a lower value.
+  * Episode numbers are reversed, meaning more recent episodes appear at the top of a season by having a lower value.
 * ``season_by_year__episode_by_download_index``
-   * Episodes are numbered by the download order. NOTE that this fetched using
+  
-     the length of the download archive. Do not use if you intend to remove
+  * Episodes are numbered by the download order. NOTE that this is fetched using the length of the download archive. Do not use if you intend to remove old videos.
-     old videos.
 
-Usage
+An example of a subscription that will be played on Kodi, organized by year with the most recent episode at the top (having a lower episode number), with a genre of "Pop":
-~~~~~
-
-A preset/subscription requires specifying a player and episode formatting preset
-and overriding the following variables:
 
 .. code-block:: yaml
+  :caption: subscriptions.yaml
 
-  rick_a_tv_show_by_date:
+  __preset__:
-    preset:
-      - "jellyfin_tv_show_by_date"
-      - "season_by_year__episode_by_month_day"
     overrides:
-      # required
+      tv_show_directory: "/tv_shows"
-      tv_show_name: "Rick A"
-      tv_show_directory: "/path/to/youtube_shows"
-      url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
-      # can be modified from their default value
-      # tv_show_genre: "ytdl-sub"
-      # tv_show_content_rating: "TV-14"
-      # episode_title: "{upload_date_standardized} - {title}"
-      # episode_description: "{webpage_url}"
 
-In addition, you can add additional URLs to create a single TV by using the override variables
+  kodi_tv_show_by_date:
-``url2``, ``url3``, ..., ``url20``:
+    season_by_year_episode_by_month_day_reversed:
+      = Pop:
+        "Rick A": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
+
+You can also choose to combine multiple URLs into one show. This will result in your videos being downloaded to the same folder, and the episode numbers being shared between them (so you won't have two episode 10's, for example). Note that you may :ytdl-sub-gh:`experience issues <issues/833>` if you use more than 20 URLs at this time.
 
 .. code-block:: yaml
+  :caption: subscriptions.yaml
 
+  __preset__:
     overrides:
-      tv_show_name: "Rick A"
+      tv_show_directory: "/tv_shows"
-      tv_show_directory: "/path/to/youtube_shows"
+
-      url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
+  kodi_tv_show_by_date:
-      url2: "https://www.youtube.com/@just.rick_6"
+    season_by_year_episode_by_month_day_reversed:
+      = Pop:
+        "~Rick A": 
+          url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
+          url2: "https://www.youtube.com/@just.rick_6"
 
 
 TV Show Collection
 ------------------
 
-TV Show Collections are made up from multiple URLs, where each URL is a season.
+TV Show Collections are made up of multiple URLs, where each URL is a season.
 If a video belongs to multiple URLs (i.e. a channel and a channel's playlist),
-it will resolve to the bottom-most season.
+it will resolve to the bottom-most season, as defined in the subscription.
 
 Two main use cases of a collection are:
    1. Organize a YouTube channel TV show where Season 1 contains any video
@@ -119,13 +129,12 @@ Episode Formatting Presets
 * ``season_by_collection__episode_by_year_month_day``
 * ``season_by_collection__episode_by_year_month_day_reversed``
 * ``season_by_collection__episode_by_playlist_index``
-   * Only use playlist_index episode formatting for playlists that
+  
-     will be fully downloaded once and never again. Otherwise,
+  * Only use playlist_index episode formatting for playlists that will be fully downloaded once and never again. Otherwise, indices can change.
-     indices can change.
 * ``season_by_collection__episode_by_playlist_index_reversed``
 
 Season Presets
-""""""""""""""
+~~~~~~~~~~~~~~
 
 * ``collection_season_1``
 * ``collection_season_2``
@@ -135,7 +144,7 @@ Season Presets
 * ``collection_season_40``
 
 Example
-"""""""
+~~~~~~~
 
 A preset/subscription requires specifying a player, episode formatting, and
 one or more season presets, with the following override variables: