diff --git a/docs/source/guides/getting_started/first_download.rst b/docs/source/guides/getting_started/first_download.rst index 805b4cd1..1a9c057e 100644 --- a/docs/source/guides/getting_started/first_download.rst +++ b/docs/source/guides/getting_started/first_download.rst @@ -1,32 +1,39 @@ Initial Download ================ -Once you have a ``subscriptions.yaml`` file created and filled out, you can perform your first +Once you have a ``subscriptions.yaml`` file created, you can perform your first download. Access ``ytdl-sub``, navigate to the directory containing your ``subscriptions.yaml`` -file, then run the below command: +file. -.. tab-set:: +Dry Run +------- +Performing a dry run is important when applying any change to your subscriptions to +ensure output looks as expected. Dry runs will pull metadata to *simulate* a download +without actually downloading the media file. - .. tab-item:: Dry run +.. code-block:: shell - A dry run lets you check that your configuration doesn't throw any errors and what the expected output files of actually doing the download are, without actually downloading the full media. + ytdl-sub --dry-run sub subscriptions.yaml - .. code-block:: shell +Faster Iteration Cycle +---------------------- +Testing subscriptions can take quite some time to perform a full download. +This can be speed up by applying an override via command-line to set max number +of downloads. - ytdl-sub --dry-run sub +.. code-block:: shell - .. tab-item:: Normal run + ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' - A normal run will download all files as determined by your ``presets`` and, once processing is finished, move the downloaded and processed files to your ``output_directory``. +Having many subscriptions could still make this dry run take a while. A subset of +subscriptions can be dry ran using a match. - .. code-block:: shell +.. code-block:: shell - ytdl-sub sub + :caption: Only run subscriptions that have PBS in their names - .. tab-item:: One-time download + ytdl-sub --dry-run sub subscriptions.yaml -o '--ytdl_options.max_downloads 3' --match PBS - Sometimes you may only want to download media once, in which case adding them to your ``subscriptions.yaml`` file is unneccessary. As an example, the below code will download the same videos as our subscription file: - - .. code-block:: shell - - ytdl-sub dl --preset "Jellyfin TV Show by Date" --overrides.subscription_name "NOVA PBS" --overrides.subscription_value "https://www.youtube.com/@novapbs" --overrides.tv_show_genre "Documentaries" \ No newline at end of file +Downloading +----------- +WIP \ No newline at end of file diff --git a/docs/source/guides/getting_started/first_sub.rst b/docs/source/guides/getting_started/first_sub.rst index f13affbb..22e4bf7d 100644 --- a/docs/source/guides/getting_started/first_sub.rst +++ b/docs/source/guides/getting_started/first_sub.rst @@ -48,6 +48,12 @@ 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. +.. note:: + It is tempting to put any override underneath ``overrides``. Keep in mind that this section + is solely for variable defining. Other :ref:`plugins ` need to be + set at the same indentation level as ``overrides``, not within it. + + ------------------------------------- .. code-block:: yaml diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index 12f8a84c..c8eb91c0 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -25,7 +25,7 @@ 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. +- ``preset``: A media profile comprised of 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 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.