documentation

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.

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'