From b979f3c3cbaef32227846a44979d92fa1a2d68d2 Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Sat, 23 Nov 2024 11:59:32 -0800 Subject: [PATCH 1/4] [DOCS] Rewrite getting started --- .../guides/getting_started/first_sub.rst | 29 ++++----- docs/source/guides/getting_started/index.rst | 62 +++++++------------ 2 files changed, 36 insertions(+), 55 deletions(-) diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst index 1043960ee..f13affbbd 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 something like this: +Your first subscription file should look something like this: .. code-block:: yaml :linenos: @@ -45,6 +45,9 @@ Lets break this down: The first :ref:`__preset__ ` section is where we can set modifications that apply to every subscription in this file. +This snippet specifically adds two :ref:`override ` variables, +which are used by the presets below. + ------------------------------------- .. code-block:: yaml @@ -73,6 +76,8 @@ subscriptions to look like TV shows in the Jellyfin media player (can be changed 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. +This preset expects the variable ``tv_show_directory`` to be set, which we do above. + ------------------------------------- .. code-block:: yaml @@ -82,17 +87,11 @@ subscriptions underneath it will *inherit* this preset. = 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. +setting the genre. This value will get written to the respective metadata tags for both TV show +and music presets. + +Behind the scenes, this sets the override variable ``subscription_indent_1``. Read more about +subscription syntax :ref:`here `. ------------------------------------- @@ -104,8 +103,10 @@ output directory. "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 `, +and the subscription value to ``https://www.youtube.com/@novapbs``. + +To see how presets ingest subscription definitions, refer to the +:ref:`preset references `, we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable. ------------------------------------- diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 3aa856bc5..21dc2be16 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -3,23 +3,20 @@ Getting Started Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process: -- Create your configuration file (if the :doc:`/prebuilt_presets/index` don't fit your needs) - Create your subscription file -- Automate starting YTDL-Sub +- Automate starting ytdl-sub +- (Optional) Create a custom configuration file if further customization is needed + Prerequisite Knowledge ---------------------- -.. _navigate directories: https://en.wikipedia.org/wiki/Cd_(command) -.. _YAML syntax: https://yaml.org/spec/1.2.2/#chapter-2-language-overview - - In order to use ``ytdl-sub`` in any of the forms listed in these docs, you will need some basic knowledge. Be sure that you: - ☑ Can `navigate directories`_ in a command line interface (or CLI) + ☑ Can navigate directories in a command line interface (or CLI) - ☑ Have a basic understanding of `YAML syntax`_ + ☑ Have a basic understanding of YAML syntax If you plan on using the headless image of ``ytdl-sub``, you: ☑ Can use ``nano`` or ``vim`` to edit OR @@ -31,48 +28,31 @@ Additional useful (but not required) knowledge: Overview -------- -``ytdl-sub`` uses two types of YAML files: - -subscriptions.yaml -~~~~~~~~~~~~~~~~~~ -Defines ``subscriptions``, which specify the media we want to recurrently download, like YouTube -channels and playlists, SoundCloud artists, or any -:yt-dlp:`yt-dlp supported site `. ``subscriptions`` use ``presets`` -to define how ``ytdl-sub`` should handle downloading, processing, and saving them. - -``ytdl-sub`` comes packaged with many -:ref:`prebuilt presets ` -that will play nicely with well-known media players. -config.yaml +Terminology ~~~~~~~~~~~ -To customize ``ytdl-sub`` to beyond the prebuilt presets, you will need a ``config.yaml`` file. This -file is where custom ``presets`` can be defined to orchestrate ``ytdl-sub`` to your very specific needs. -Running ytdl-sub -~~~~~~~~~~~~~~~~ -To invoke ``ytdl-sub`` to download subscriptions, use the following command: +Must-know terminology: +- ``subscription``: URL(s) that you want to download with specific metadata requirements. +- ``preset``: Reusable YAML configuration, that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets. +- ``prebuilt preset``: Presets that are included in ``ytdl-sub``. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption. +- ``override``: Verb describing the act of overriding something in a parent preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from. +- ``override variables``: User-defined variables that a preset will use in its definition. +- ``subscription file``: The file to specify all of your subscriptions and some override variables. -.. tab-set-code:: +Intermediate terminology: +- ``plugin``: Modular logic to apply to a subscription. To use a plugin, it must be defined in a preset. +- ``config file``: An optional file where you can define custom presets and other advanced configuration. +- ``yt-dlp``: The underlying application that handles downloading for ytdl-sub. - .. code-block:: shell - - ytdl-sub sub subscriptions.yaml - - .. code-block:: powershell - - ytdl-sub.exe sub subscriptions.yaml - -``ytdl-sub`` initially downloads all files to a defined ``working_directory``. This is a temporary -storage spot for metadata and media files so that errors during processing- if they occur- don't -affect your existing media library. Once all file processing is complete, your media files are -moved to the ``output_directory``. +Advanced terminology: +- ``entry variables``: Variables that derive from a downloaded yt-dlp entry. +- ``static variables``: Variables that do not have a dependency to entry variables. +- ``scripting``: Syntax that allows the use of entry variables, static variables, and functions in override variables. Ready to Start? --------------- -Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started: - :doc:`Step 1: Initial Subscriptions ` :doc:`Step 2: Your First Download ` From 41b8a7168eef0b3a7402804ef677fa9575e98b87 Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Sat, 23 Nov 2024 12:07:43 -0800 Subject: [PATCH 2/4] more --- docs/source/guides/getting_started/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 21dc2be16..5a0d82a71 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -31,13 +31,12 @@ Overview Terminology ~~~~~~~~~~~ - Must-know terminology: - ``subscription``: URL(s) that you want to download with specific metadata requirements. - ``preset``: Reusable YAML configuration, that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets. - ``prebuilt preset``: Presets that are included in ``ytdl-sub``. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption. - ``override``: Verb describing the act of overriding something in a parent preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from. -- ``override variables``: User-defined variables that a preset will use in its definition. +- ``override variables``: User-defined variables that are intended to *override* something. - ``subscription file``: The file to specify all of your subscriptions and some override variables. Intermediate terminology: From 75c5766c94c892b7483777bb44b20edff7b589c1 Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Sat, 23 Nov 2024 12:08:44 -0800 Subject: [PATCH 3/4] spacing --- docs/source/guides/getting_started/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 5a0d82a71..ffdcaf746 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -31,6 +31,7 @@ Overview Terminology ~~~~~~~~~~~ + Must-know terminology: - ``subscription``: URL(s) that you want to download with specific metadata requirements. - ``preset``: Reusable YAML configuration, that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets. @@ -40,11 +41,13 @@ Must-know terminology: - ``subscription file``: The file to specify all of your subscriptions and some override variables. Intermediate terminology: + - ``plugin``: Modular logic to apply to a subscription. To use a plugin, it must be defined in a preset. - ``config file``: An optional file where you can define custom presets and other advanced configuration. - ``yt-dlp``: The underlying application that handles downloading for ytdl-sub. Advanced terminology: + - ``entry variables``: Variables that derive from a downloaded yt-dlp entry. - ``static variables``: Variables that do not have a dependency to entry variables. - ``scripting``: Syntax that allows the use of entry variables, static variables, and functions in override variables. From 5e5b10885193312e8792f8b67787ebc17cfea85d Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Sun, 24 Nov 2024 08:58:44 -0800 Subject: [PATCH 4/4] more --- docs/source/guides/getting_started/index.rst | 23 +++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index ffdcaf746..12f8a84c9 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -1,13 +1,6 @@ Getting Started =============== -Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process: - -- Create your subscription file -- Automate starting ytdl-sub -- (Optional) Create a custom configuration file if further customization is needed - - Prerequisite Knowledge ---------------------- @@ -26,17 +19,15 @@ If you plan on using the headless image of ``ytdl-sub``, you: Additional useful (but not required) knowledge: ☑ Understanding how :yt-dlp:`\ ` works -Overview --------- - Terminology -~~~~~~~~~~~ +----------- Must-know terminology: + - ``subscription``: URL(s) that you want to download with specific metadata requirements. - ``preset``: Reusable YAML configuration, that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets. -- ``prebuilt preset``: Presets that are included in ``ytdl-sub``. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption. -- ``override``: Verb describing the act of overriding something in a parent preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from. +- ``prebuilt preset``: Presets that are included in ytdl-sub. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption. +- ``override``: Verb describing the act of overriding something in a preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from. - ``override variables``: User-defined variables that are intended to *override* something. - ``subscription file``: The file to specify all of your subscriptions and some override variables. @@ -54,6 +45,12 @@ Advanced terminology: Ready to Start? --------------- +Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process: + +- Create your subscription file +- Automate starting ytdl-sub +- (Optional) Create a custom configuration file if further customization is needed + :doc:`Step 1: Initial Subscriptions `