From 8e6a2cb98e9bcdaaf6312c9276f1a9b3e26c4c7e Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Tue, 20 Feb 2024 21:04:13 -0800 Subject: [PATCH] [DOCS] Rewrite first subscription documentation (#932) --- .../guides/getting_started/first_download.rst | 6 +- .../guides/getting_started/first_sub.rst | 123 +++++++++++++++++- 2 files changed, 121 insertions(+), 8 deletions(-) diff --git a/docs/source/guides/getting_started/first_download.rst b/docs/source/guides/getting_started/first_download.rst index 8babc19e..805b4cd1 100644 --- a/docs/source/guides/getting_started/first_download.rst +++ b/docs/source/guides/getting_started/first_download.rst @@ -1,7 +1,9 @@ Initial Download ================ -Once you have the ``config.yaml`` and ``subscriptions.yaml`` files created and filled out, you can perform your first download. Access ``ytdl-sub``, navigate to the directory containing your ``config.yaml`` and ``subscriptions.yaml`` files, then run the below command: +Once you have a ``subscriptions.yaml`` file created and filled out, you can perform your first +download. Access ``ytdl-sub``, navigate to the directory containing your ``subscriptions.yaml`` +file, then run the below command: .. tab-set:: @@ -27,4 +29,4 @@ Once you have the ``config.yaml`` and ``subscriptions.yaml`` files created and f .. code-block:: shell - ytdl-sub dl --preset "My Favorite YouTube Channels" --overrides.subscription_name "Rick Astley" --overrides.subscription_value "https://www.youtube.com/@RickAstleyYT/videos" \ No newline at end of file + ytdl-sub dl --preset "Jellyfin TV Show by Date" --overrides.subscription_name "NOVA PBS" --overrides.subscription_value "https://www.youtube.com/@novapbs" --overrides.tv_show_genre "Documentaries" \ No newline at end of file diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst index b2a83a88..1043960e 100644 --- a/docs/source/guides/getting_started/first_sub.rst +++ b/docs/source/guides/getting_started/first_sub.rst @@ -1,7 +1,7 @@ Initial Subscription ==================== -Your first subscription should look similar to the below: +Your first subscription should look something like this: .. code-block:: yaml :linenos: @@ -9,13 +9,124 @@ Your first subscription should look similar to the below: __preset__: overrides: tv_show_directory: "/tv_shows" + music_directory: "/music" - "My Favorite YouTube Channels": - "Rick Astley": "https://www.youtube.com/@RickAstleyYT/videos" + # Can choose between: + # - Plex TV Show by Date: + # - Jellyfin TV Show by Date: + # - Kodi TV Show by Date: + # + Jellyfin TV Show by Date: + = Documentaries: + "NOVA PBS": "https://www.youtube.com/@novapbs" + + = Kids | = TV-Y: + "Jake Trains": "https://www.youtube.com/@JakeTrains" + + YouTube Releases: + = Jazz: # Sets genre tag to "Jazz" + "Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases" + + YouTube Full Albums: + = Lofi: + "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i" + +Lets break this down: + +.. code-block:: yaml + :lineno-start: 1 + + __preset__: + overrides: + tv_show_directory: "/tv_shows" + music_directory: "/music" -The first three lines in this subscription file define where to save the downloaded files associated with all subscriptions in this file. +The first :ref:`__preset__ ` section is where we +can set modifications that apply to every subscription 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 `, in this case a YouTube channel. \ No newline at end of file +.. code-block:: yaml + :lineno-start: 6 + + # Can choose between: + # - Plex TV Show by Date: + # - Jellyfin TV Show by Date: + # - Kodi TV Show by Date: + # + +Lines 6-10 are comments that get ignored when parsing YAML since they are prefixed with ``#``. +It is good practice to leave informative comments in your config or subscription files to remind +yourself of various things. + +------------------------------------- + +.. code-block:: yaml + :lineno-start: 11 + + Jellyfin TV Show by Date: + +On line 11, we set the key to ``Jellyfin TV Show by Date``. This is a +:ref:`prebuilt preset ` that configures +subscriptions to look like TV shows in the Jellyfin media player (can be changed to +one of the presets outlined in the comment above). Setting it as a YAML key implies that all +subscriptions underneath it will *inherit* this preset. + +------------------------------------- + +.. code-block:: yaml + :lineno-start: 11 + + Jellyfin TV Show by Date: + = Documentaries: + +Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are +setting the +:ref:`subscription indent variable `. +For TV Show presets, the first subscription indent variable maps to the TV show's genre. +Setting subscription indent variables as a key implies all subscriptions underneath it will +have this variable set. + +To better understand what variables are used in prebuilt presets, refer to the +:ref:`prebuilt preset reference `. +Here you will see the underlying variables used in prebuilt presets that can be overwritten. +We already overwrote a few of the variables in the ``__preset__`` section above to define our +output directory. + +------------------------------------- + +.. code-block:: yaml + :lineno-start: 11 + + Jellyfin TV Show by Date: + = 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``, +and the subscription value to ``https://www.youtube.com/@novapbs``. Referring to the +:ref:`TV show preset reference `, +we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable. + +------------------------------------- + +.. code-block:: yaml + :lineno-start: 11 + + Jellyfin TV Show by Date: + = Documentaries: + "NOVA PBS": "https://www.youtube.com/@novapbs" + + = 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``. +This means we'll inherit the TV show preset, but not the documentaries indent variable. We instead +set the indent variables to ``= Kids | = TV-Y``. This sets two indent variables. We can set +multiple presets and/or indent variables on the same key by using ``|`` as a separator. + +Referring to the +:ref:`TV show preset reference `, the first +two indent variables map to the TV show genre and TV show content rating. + +The above info should be enough to understand the rest of the subscription file. \ No newline at end of file