diff --git a/docs/source/config_reference/subscription_yaml.rst b/docs/source/config_reference/subscription_yaml.rst index a28a5e6e..0505d7bb 100644 --- a/docs/source/config_reference/subscription_yaml.rst +++ b/docs/source/config_reference/subscription_yaml.rst @@ -7,9 +7,28 @@ to download in condensed YAML. .. hint:: - Read the :ref:`getting started guide ` + Read the :ref:`getting started guide ` 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 ` +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. + +.. code-block:: yaml + + __preset__: + overrides: + tv_show_directory: "/tv_shows" + + ytdl_options: + cookiefile: "/config/cookie.txt" + + Layout ------ A subscription file is comprised of YAML keys and values. Keys can be either diff --git a/docs/source/deprecation_notices.rst b/docs/source/deprecation_notices.rst index fc238128..4c5b6a37 100644 --- a/docs/source/deprecation_notices.rst +++ b/docs/source/deprecation_notices.rst @@ -46,7 +46,7 @@ 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/subscriptions_yaml:beautifying subscriptions`. ``__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 --------- diff --git a/docs/source/guides/getting_started/advanced_configuration.rst b/docs/source/guides/getting_started/advanced_configuration.rst deleted file mode 100644 index 7ab05e31..00000000 --- a/docs/source/guides/getting_started/advanced_configuration.rst +++ /dev/null @@ -1,56 +0,0 @@ -Advanced Configuration -====================== - -If the :doc:`prebuilt presets ` aren't suitable for your needs, you may want to set up an advanced configuration. - -Layout of a Config file ------------------------ - -The layout of the ``config.yaml`` file is relatively straightforward: - -.. code-block:: yaml - - presets: - - preset_name: - plugin1: - plugin1_option1: value1 - -This creates a preset named ``preset_name``, which contains the made-up -:doc:`plugin ` ``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: - preset: - - "Jellyfin TV Show by Date" - - overrides: - tv_show_directory: "/ytdl_sub_tv_shows" - - TV Show Only Recent: - preset: - - "TV Show" - - "Only Recent" - - overrides: - only_recent_date_range: "3weeks" - -This creates two presets: - -* ``TV Show`` - * Inherits the :doc:`prebuilt ` ``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. diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index 9c6e795d..4b80a18b 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -150,7 +150,7 @@ Setting Override Variables ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: yaml - :lineno-start: 20 + :lineno-start: 23 overrides: tv_show_directory: "/ytdl_sub_tv_shows" @@ -187,7 +187,7 @@ Below shows a complete subscription file using the above two custom presets. "Jake Trains": "https://www.youtube.com/@JakeTrains" TV Show Only Recent: - = News + = News: "BBC News": "https://www.youtube.com/@BBCNews" Notice how we do not need to define ``tv_show_directory`` in the ``__preset__`` section diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst index a3cd2005..7dd5c22f 100644 --- a/docs/source/guides/getting_started/first_sub.rst +++ b/docs/source/guides/getting_started/first_sub.rst @@ -42,7 +42,7 @@ Let's break this down: music_directory: "/music" -The first :ref:`__preset__ ` section is where we +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, @@ -96,8 +96,10 @@ Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, 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 `. +Behind the scenes, this sets the override variable ``subscription_indent_1``. Further documentation +can be found here for +:ref:`subscription syntax ` and +:ref:`subscription variables `. ------------------------------------- diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index aed76dab..c86ed757 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -45,36 +45,13 @@ 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 ` - -:doc:`Step 2: Your First Download ` - -:doc:`Step 3: Automating Downloads ` - -Want to go a step further? - -If you want to use atypical paths or specific configuration options, check out :doc:`Basic Configuration ` - -For tips on creating your own presets when the prebuilt presets aren't cutting it, check out :doc:`Advanced Configuration ` - -Other docs that may be of use: - -:doc:`/prebuilt_presets/index` +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:: - :hidden: - :caption: Getting Started Guide - :maxdepth: 1 + :maxdepth: 2 first_sub first_download automating_downloads first_config - advanced_configuration