From a642028d7b757d812c34e296febe9a58c9987697 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Sun, 24 Aug 2025 09:17:38 -0700 Subject: [PATCH] [DOCS] Clarify the = YAML key prefix (#1297) This is another change that touches the generated docs, so after finishing my writing, I copied the change to `./docs/source/config_reference/scripting/static_variables.rst` into the corresponding docstring in `./src/ytdl_sub/entries/variables/override_variables.py` and formatted it as a docstring. Then I ran: $ REGENERATE_DOCS=1 tox exec -e "py" -- pytest tests/unit/docgen/test_docgen.py But all that did was revert the changes to `./docs/source/config_reference/scripting/static_variables.rst`. IOW, it did *not* update the rST from the changed docstring. --- .../scripting/static_variables.rst | 15 ++++++++++----- docs/source/guides/getting_started/index.rst | 7 +++++-- docs/source/prebuilt_presets/music.rst | 5 ----- .../entries/variables/override_variables.py | 15 ++++++++++----- 4 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/source/config_reference/scripting/static_variables.rst b/docs/source/config_reference/scripting/static_variables.rst index fb7699b1..ff69c0ab 100644 --- a/docs/source/config_reference/scripting/static_variables.rst +++ b/docs/source/config_reference/scripting/static_variables.rst @@ -31,16 +31,21 @@ otherwise. subscription_indent_i ~~~~~~~~~~~~~~~~~~~~~ -For subscriptions in the form of +For subscriptions where the ancestor keys contain the ``= ...`` prefix, the +variables ``subscription_indent_1``, ``subscription_indent_2``, and so on get +set to each subsequent value. For example, given the following subscriptions +file snippet: .. code-block:: yaml - Preset | = Indent Value 1: - = Indent Value 2: + Preset 1 | = Indent Value 1 | Preset 2: + Preset 3 | = Indent Value 2 | Preset 4: "Subscription Name": "https://..." -``subscription_indent_1`` and ``subscription_indent_2`` get set to -``Indent Value 1`` and ``Indent Value 2``. +The ``{subscription_indent_1}`` variable will be ``Indent Value 1`` and +``{subscription_indent_2}`` will be ``Indent Value 2``. The most common use of +these variables is to :doc:`set the genre and rating for subscriptions from the +YAML keys <../prebuilt_presets/tv_show>`. subscription_map ~~~~~~~~~~~~~~~~ diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 33ba7126..f325f862 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -91,8 +91,11 @@ ancestor keys above that subscription describe the shared presets of that subscr and all the other descendant subscriptions under them. Genres are also more often shared between subscriptions than not. To accommodate that -reality, the ancestor keys of subscriptions may also use the special ``= ...`` prefix to -specify genres that also apply to all descendant subscriptions. +reality, the ancestor keys of subscriptions may also use :ref:`the special '= ...' +prefix to pass specific overrides +` supported by the +preset. By convention in the built-in presets, the first ``= ...`` value specifies the +genre for all descendant subscriptions. Finally, ancestor keys may use the ``... | ...`` special character to combine multiple presets and/or genres for the descendant subscriptions beneath. diff --git a/docs/source/prebuilt_presets/music.rst b/docs/source/prebuilt_presets/music.rst index edb92b02..1713a849 100644 --- a/docs/source/prebuilt_presets/music.rst +++ b/docs/source/prebuilt_presets/music.rst @@ -5,11 +5,6 @@ Music Presets Music downloadable by yt-dlp comes in many flavors. ``ytdl-sub`` offers a suite of various presets for handling some of the most popular forms of uploaded music content. -.. hint:: - - The subscription *value* (denoted by =) will set the genre tag for all music scraped - under its key for all music presets. - YouTube Releases ---------------- diff --git a/src/ytdl_sub/entries/variables/override_variables.py b/src/ytdl_sub/entries/variables/override_variables.py index 42bb4498..e9b3da07 100644 --- a/src/ytdl_sub/entries/variables/override_variables.py +++ b/src/ytdl_sub/entries/variables/override_variables.py @@ -55,16 +55,21 @@ class SubscriptionVariables: @staticmethod def subscription_indent_i(index: int) -> StringVariable: """ - For subscriptions in the form of + For subscriptions where the ancestor keys contain the ``= ...`` prefix, the + variables ``subscription_indent_1``, ``subscription_indent_2``, and so on get + set to each subsequent value. For example, given the following subscriptions + file snippet: .. code-block:: yaml - Preset | = Indent Value 1: - = Indent Value 2: + Preset 1 | = Indent Value 1 | Preset 2: + Preset 3 | = Indent Value 2 | Preset 4: "Subscription Name": "https://..." - ``subscription_indent_1`` and ``subscription_indent_2`` get set to - ``Indent Value 1`` and ``Indent Value 2``. + The ``{subscription_indent_1}`` variable will be ``Indent Value 1`` and + ``{subscription_indent_2}`` will be ``Indent Value 2``. The most common use of + these variables is to :doc:`set the genre and rating for subscriptions from the + YAML keys <../prebuilt_presets/tv_show>`. """ return StringVariable( variable_name=f"subscription_indent_{index + 1}", definition="{ %string('') }"