diff --git a/docs/source/code_reference/prebuilt_presets.rst b/docs/source/code_reference/prebuilt_presets.rst deleted file mode 100644 index f91778c2..00000000 --- a/docs/source/code_reference/prebuilt_presets.rst +++ /dev/null @@ -1,87 +0,0 @@ -================ -Prebuilt Presets -================ -If you are ready to start downloading, see our -`examples directory `_ -for ready-to-use configs and subscriptions. Read through them carefully before use. - -Helper Presets -============== - -By themselves, these presets won't get your media downloaded, but they're useful for condensing multi-line modifications to other presets into a single line through :ref:`guides/getting_started/advanced_configuration:preset inheritance`. - -best_video_quality ------------------- - -This preset: - ``1`` Is named ``best_video_quality`` - - ``2`` Searches for the best video and audio formats available to download - - ``4`` Uses the ``mp4`` extension when merging multiple formats into one file - -.. code-block:: yaml - :linenos: - - best_video_quality: - format: "bestvideo+bestaudio/best" - ytdl_options: - merge_output_format: "mp4" - -max_1080p ---------- - -This preset: - ``1`` Is named ``max_1080p`` - - ``2`` Searches for the best video (up to 1080p) and audio formats to download - - ``4`` Uses the ``mp4`` extension when merging multiple formats into one file - - -.. code-block:: yaml - :linenos: - - max_1080p: - format: "(bv*[height<=1080]+bestaudio/best[height<=1080])" - ytdl_options: - merge_output_format: "mp4" - -chunk_initial_download ----------------------- - -This preset: - ``1`` Is named ``chunk_initial_download`` - - ``3`` Downloads up to 20 videos per subscription per run - - ``4`` Reverses the subscription playlist, which starts from the beginning of the playlist in most cases - - ``5`` Will not stop downloading videos when it reaches a video that exists, but will skip the existing videos instead of redownloading them - - ``6`` Will stop downloading videos if a yt-dlp reject occurs - -.. code-block:: yaml - :linenos: - - chunk_initial_download: - ytdl_options: - max_downloads: 20 - playlistreverse: True - break_on_existing: False - break_on_reject: True - -Only Recent ------------ - -This preset: - ``1`` Is named "Only Recent" - - ``3`` Only attempts to download videos uploaded after ``today-{only_recent_date_range}``, where ``{only_recent_date_range}`` is set as an override variable in your subscription or a :ref:`child preset `. - -.. code-block:: yaml - :linenos: - - "Only Recent": - date_range: - after: "today-{only_recent_date_range}" \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 466c9039..b64f9f03 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,7 +48,7 @@ html_theme_options = { }, ], "announcement": ( - "Migration to beautiful subscriptions is now live" + "Please excuse our mess as we update these documents" ), "navigation_depth": 10, "show_toc_level": 10, @@ -69,6 +69,7 @@ extlinks = { "unraid": ("https://unraid.net/%s", "unraid%s"), "lsio": ("https://www.linuxserver.io/%s", "lsio%s"), "lsio-gh": ("https://github.com/linuxserver/%s", "%s image"), + "ytdl-sub-gh": ("https://github.com/jmbannon/ytdl-sub/%s","src %s"), } # -- Options for autodoc ---------------------------------------------------- diff --git a/docs/source/code_reference/config_yaml.rst b/docs/source/config_reference/config_yaml.rst similarity index 100% rename from docs/source/code_reference/config_yaml.rst rename to docs/source/config_reference/config_yaml.rst diff --git a/docs/source/code_reference/index.rst b/docs/source/config_reference/index.rst similarity index 57% rename from docs/source/code_reference/index.rst rename to docs/source/config_reference/index.rst index ae199305..ee50572e 100644 --- a/docs/source/code_reference/index.rst +++ b/docs/source/config_reference/index.rst @@ -1,5 +1,6 @@ -Code Reference -============== +================ +Config Reference +================ This section contains direct references to the code of ``ytdl-sub`` and information on how it functions. @@ -7,8 +8,4 @@ This section contains direct references to the code of ``ytdl-sub`` and informat config_yaml subscriptions_yaml plugins - entry_variables - override_variables - config - prebuilt_presets - scripting_functions \ No newline at end of file + scripting/index \ No newline at end of file diff --git a/docs/source/code_reference/plugins.rst b/docs/source/config_reference/plugins.rst similarity index 100% rename from docs/source/code_reference/plugins.rst rename to docs/source/config_reference/plugins.rst diff --git a/docs/source/code_reference/config.rst b/docs/source/config_reference/scripting/config_types.rst similarity index 91% rename from docs/source/code_reference/config.rst rename to docs/source/config_reference/scripting/config_types.rst index 4b0593cd..31273cde 100644 --- a/docs/source/code_reference/config.rst +++ b/docs/source/config_reference/scripting/config_types.rst @@ -1,5 +1,7 @@ -Config Types ------------- +================== +Config Field Types +================== + The ``config.yaml`` uses various types for its configurable fields. Below is a definition for each type. .. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator() diff --git a/docs/source/code_reference/entry_variables.rst b/docs/source/config_reference/scripting/entry_variables.rst similarity index 100% rename from docs/source/code_reference/entry_variables.rst rename to docs/source/config_reference/scripting/entry_variables.rst diff --git a/docs/source/config_reference/scripting/index.rst b/docs/source/config_reference/scripting/index.rst new file mode 100644 index 00000000..c6ae4532 --- /dev/null +++ b/docs/source/config_reference/scripting/index.rst @@ -0,0 +1,9 @@ +========= +Scripting +========= + +.. toctree:: + entry_variables + override_variables + scripting_functions + config_types \ No newline at end of file diff --git a/docs/source/code_reference/override_variables.rst b/docs/source/config_reference/scripting/override_variables.rst similarity index 100% rename from docs/source/code_reference/override_variables.rst rename to docs/source/config_reference/scripting/override_variables.rst diff --git a/docs/source/code_reference/scripting_functions.rst b/docs/source/config_reference/scripting/scripting_functions.rst similarity index 100% rename from docs/source/code_reference/scripting_functions.rst rename to docs/source/config_reference/scripting/scripting_functions.rst diff --git a/docs/source/code_reference/subscriptions_yaml.rst b/docs/source/config_reference/subscriptions_yaml.rst similarity index 92% rename from docs/source/code_reference/subscriptions_yaml.rst rename to docs/source/config_reference/subscriptions_yaml.rst index 82f65c4f..bf68394c 100644 --- a/docs/source/code_reference/subscriptions_yaml.rst +++ b/docs/source/config_reference/subscriptions_yaml.rst @@ -5,7 +5,7 @@ Subscriptions File subscriptions.yaml ------------------ -The ``subscriptions.yaml`` file is where we use our :ref:`code_reference/config_yaml:presets` in the :ref:`code_reference/config_yaml:config.yaml` +The ``subscriptions.yaml`` file is where we use our :ref:`config_reference/config_yaml:presets` in the :ref:`config_reference/config_yaml:config.yaml` to define a ``subscription``: something we want to recurrently download such as a specific channel or playlist. @@ -102,7 +102,7 @@ parent preset: File Preset ~~~~~~~~~~~ -NOTE: This is deprecated in favor of using the method in :ref:`code_reference/subscriptions_yaml:beautifying subscriptions`. +NOTE: This is deprecated in favor of using the method in :ref:`config_reference/subscriptions_yaml:beautifying subscriptions`. You can apply a preset to all subscriptions in the ``subscription.yaml`` file by using the file-wide ``__preset__``: @@ -124,7 +124,7 @@ subscriptions automatically set ``__preset__`` as a ``parent preset``. Subscription Value ~~~~~~~~~~~~~~~~~~~ -NOTE: This is deprecated in favor of using the method in :ref:`code_reference/subscriptions_yaml:beautifying subscriptions`. +NOTE: This is deprecated in favor of using the method in :ref:`config_reference/subscriptions_yaml:beautifying subscriptions`. With a clever config and use of ``__preset__``, your subscriptions can typically boil down to a name and url. You can set ``__value__`` to the name of an override variable, @@ -147,4 +147,4 @@ Using the example above, we can do: "Brandon Acker": "https://www.youtube.com/@brandonacker" Traditional subscriptions that can override presets will still work when using ``__value__``. -``__value__`` can also be set within a :ref:`code_reference/config_yaml:config.yaml`. \ No newline at end of file +``__value__`` can also be set within a :ref:`config_reference/config_yaml:config.yaml`. \ No newline at end of file diff --git a/docs/source/deprecation_notices.rst b/docs/source/deprecation_notices.rst index fdbfc929..29e3c5b0 100644 --- a/docs/source/deprecation_notices.rst +++ b/docs/source/deprecation_notices.rst @@ -7,7 +7,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:`code_reference/subscriptions_yaml:beautifying subscriptions`. ``__preset__`` will still be supported for the time being. +:ref:`config_reference/subscriptions_yaml:beautifying subscriptions`. ``__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 index 42567bad..385ed3b7 100644 --- a/docs/source/guides/getting_started/advanced_configuration.rst +++ b/docs/source/guides/getting_started/advanced_configuration.rst @@ -1,7 +1,7 @@ Advanced Configuration ====================== -If the :doc:`prebuilt presets ` aren't suitable for your needs, you may want to set up an 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 ----------------------- diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index 40c47e32..d8a074b4 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -24,7 +24,7 @@ The first two lines in this ``config.yaml`` file are the ``configuration``, and Line 4 begins the definition of your custom ``presets``, with line 5 being the name of your first custom ``preset``. -Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/code_reference/prebuilt_presets` to expand on; these ``presets`` already indicate that the downloaded files should be: +Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/prebuilt_presets/index` to expand on; these ``presets`` already indicate that the downloaded files should be: - in a format usable by, and with metadata accessible to, Jellyfin - sorted by upload date, and diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index a6c7b043..0562c78b 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -3,7 +3,7 @@ Getting Started Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process: -- Create your configuration file (if the :doc:`/code_reference/prebuilt_presets` don't fit your needs) +- Create your configuration file (if the :doc:`/prebuilt_presets/index` don't fit your needs) - Create your subscription file - Automate starting YTDL-Sub @@ -69,7 +69,7 @@ Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit Other docs that may be of use: -:doc:`/code_reference/prebuilt_presets` +:doc:`/prebuilt_presets/index` :doc:`examples` diff --git a/docs/source/index.rst b/docs/source/index.rst index 1763bdb8..5f8d748d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,20 +1,21 @@ ytdl-sub User Guide =================== + .. toctree:: :maxdepth: 2 + :titlesonly: introduction guides/index - faq/index - code_reference/index - presets + prebuilt_presets/index usage + config_reference/index + faq/index deprecation_notices .. note:: End goal similar to: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html Initial plans: - - step-by-step noob install instructions for each platform - pages for each prebuilt preset, showing which variables that can be overridden to do different things (i.e. episode_title) - new wiki walkthrough that uses the README config as a starting point, and gradually adds custom changes - pages for how to enable custom metadata agents for Kodi/Plex/jellyfin diff --git a/docs/source/presets.rst b/docs/source/prebuilt_presets/index.rst similarity index 98% rename from docs/source/presets.rst rename to docs/source/prebuilt_presets/index.rst index 6eb7b708..f04cbeb7 100644 --- a/docs/source/presets.rst +++ b/docs/source/prebuilt_presets/index.rst @@ -1,9 +1,9 @@ Presets ======= + ``ytdl-sub`` offers a number of built-in presets using best practices for formatting media in various players. For advanced users, you can find the prebuilt preset -definitions -`here `_. +definitions :ytdl-sub-gh:`here `. TV Shows --------