diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index 0f98b84e..275526f5 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -242,3 +242,22 @@ Be sure to tell ytdl-sub to use your config by using the argument ``--config If you run ytdl-sub in the same directory, and the config file is named ``config.yaml``, it will use it by default. + +Visualizing a subscription in Preset form +----------------------------------------- + +Subscription file syntax is designed to minimize boiler-plate when authoring new subscriptions. +You can unpack any subscription using the ``inspect`` sub-command to see its boiler-plate *preset format*. + +.. code-block:: bash + + ytdl-sub inspect --config /path/to/config.yaml --match "BBC News" /path/to/subscriptions.yaml + +This can be utilized for numerous purposes including: + +* Ensuring your custom preset is getting applied correctly. +* Figuring out which variables set things like file names, metadata, etc. +* Understanding how subscription syntax translates to preset representation. + +The default ``--level`` of inspect will fill in strings. Using ``--level original`` will +present the subscription's raw layout. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index cb5b827e..dc59cc99 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -112,3 +112,35 @@ Convert yt-dlp cli arguments to ytdl-sub `ytdl_options` arguments. .. code-block:: ytdl-sub cli-to-sub [YT-DLP ARGS] + +Inspect +------- +Inspect a single subscription's underlying preset representation. +This can be utilized for numerous purposes including: + +* Ensuring your custom preset is getting applied correctly. +* Figuring out which variables set things like file names, metadata, etc. +* Understanding how subscription syntax translates to preset representation. + +Usage: + +.. code-block:: bash + + ytdl-sub inspect --match "Game Chops" -mock 'title=Lets Play' examples/music_subscriptions.yaml + +.. code-block:: text + :caption: Additional Options + + -l 0,1,2,3, --level 0,1,2,3 + level of inspection to perform: + 0 - original present the subscription as-is + 1 - fill fill in defined values + 2 - resolve resolve all possible variables (default) + 3 - internal resolve all variables to their internal representation + + -m MATCH [MATCH ...], --match MATCH [MATCH ...] + match subscription names to one or more substrings, and only run those subscriptions + -o DL_OVERRIDE, --dl-override DL_OVERRIDE + override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3' + -k VAR=VALUE, --mock VAR=VALUE + ability to mock one or more variable values, i.e. --mock 'title=Lets Play'