diff --git a/docs/source/conf.py b/docs/source/conf.py index 2f8487c9..3c6033ae 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,8 @@ release = "2023.12.15" extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.extlinks", "sphinx_copybutton", "sphinx_design", ] @@ -45,9 +47,15 @@ html_theme_options = { }, ], "announcement": ( - "Migration to beautiful subscriptions is now live" + "Migration to beautiful subscriptions is now live" ), } - html_static_path = ["_static"] + + +# Make sure the all autosectionlabel targets are unique +autosectionlabel_prefix_document = True + + +extlinks = {"yt-dlp": ("https://github.com/yt-dlp/yt-dlp/%s", "yt-dlp%s")} diff --git a/docs/source/config.rst b/docs/source/config.rst index b1f05b7f..8afa014a 100644 --- a/docs/source/config.rst +++ b/docs/source/config.rst @@ -22,7 +22,7 @@ If you wish to represent paths like Windows, you will need to ``C:\\double\\bash in order to escape the backslash character. configuration -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ The ``configuration`` section contains app-wide configs applied to all presets and subscriptions. @@ -50,7 +50,7 @@ Log files are stored as :member-order: bysource presets -^^^^^^^ +~~~~~~~ ``presets`` define a `formula` for how to format downloaded media and metadata. download_strategy @@ -307,10 +307,8 @@ custom variables: ``{output_directory}``, ``{playlist_name}``, and ``{url}``. Th the `parent preset`_ to ``playlist_preset_ex``, and must define the variables ``{playlist_name}`` and ``{url}`` since the preset did not. -.. _beautifying subscriptions: - Beautifying Subscriptions -^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~ Subscriptions support using presets as keys, and using keys to set override variables as values. For example: @@ -368,8 +366,8 @@ parent preset: .. _subscription value: File Preset -^^^^^^^^^^^ -NOTE: This is deprecated in favor of using the method in :ref:`beautifying subscriptions`. +~~~~~~~~~~~ +NOTE: This is deprecated in favor of using the method in :ref:`config:beautifying subscriptions`. You can apply a preset to all subscriptions in the ``subscription.yaml`` file by using the file-wide ``__preset__``: @@ -390,8 +388,8 @@ subscriptions automatically set ``__preset__`` as a `parent preset`_. Subscription Value -^^^^^^^^^^^^^^^^^^^ -NOTE: This is deprecated in favor of using the method in :ref:`beautifying subscriptions`. +~~~~~~~~~~~~~~~~~~~ +NOTE: This is deprecated in favor of using the method in :ref:`config: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, diff --git a/docs/source/deprecation_notices.rst b/docs/source/deprecation_notices.rst index 56c42d0a..8be00274 100644 --- a/docs/source/deprecation_notices.rst +++ b/docs/source/deprecation_notices.rst @@ -5,15 +5,15 @@ Oct 2023 -------- subscription preset and value -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The use of ``__value__`` will go away in Dec 2023 in favor of the method found in -:ref:`beautifying subscriptions`. ``__preset__`` will still be supported for the time being. +:ref:`config:beautifying subscriptions`. ``__preset__`` will still be supported for the time being. July 2023 --------- music_tags -^^^^^^^^^^ +~~~~~~~~~~ Music tags are getting simplified. ``tags`` will now reside directly under music_tags, and ``embed_thumbnail`` is getting moved to its own plugin (supports video files as well). Convert from: @@ -38,7 +38,7 @@ To the following: The old format will be removed in October 2023. video_tags -^^^^^^^^^^ +~~~~~~~~~~ Video tags are getting simplified as well. ``tags`` will now reside directly under video_tags. Convert from: diff --git a/docs/source/guides/getting_started/automating_downloads.rst b/docs/source/guides/getting_started/automating_downloads.rst index d20e63cb..ba7fa583 100644 --- a/docs/source/guides/getting_started/automating_downloads.rst +++ b/docs/source/guides/getting_started/automating_downloads.rst @@ -1,11 +1,14 @@ Automating Downloads ==================== -:ref:`docker-unraid-setup` +One of the key capabilities of ``ytdl-sub`` is how well it runs without user input, but to take advantage of this you must set up scheduling to execute the commands at some interval. How you set up this scheduling depends on which version of ``ytdl-sub`` you downloaded. -:ref:`linux-setup` -:ref:`windows-setup` +:ref:`Guide for Docker and Unraid Containers ` + +:ref:`Guide for Linux ` + +:ref:`Guide for Windows ` .. _cron tab manpage: https://man7.org/linux/man-pages/man5/crontab.5.html#EXAMPLE_CRON_FILE @@ -118,6 +121,12 @@ Docker and Unraid Linux ----- +.. code-block:: shell + + crontab -e + 0 */6 * * * /config/run_cron + + .. _windows-setup: diff --git a/docs/source/guides/getting_started/first_config.rst b/docs/source/guides/getting_started/first_config.rst index 41ca4cfd..320730f3 100644 --- a/docs/source/guides/getting_started/first_config.rst +++ b/docs/source/guides/getting_started/first_config.rst @@ -1,2 +1,33 @@ Initial Configuration ===================== + +Your first configuration will look pretty simple: + +.. code-block:: yaml + :linenos: + + configuration: + working_directory: '.ytdl-sub-downloads' + + presets: + "My Favorite YouTube Channels": + preset: + - "Jellyfin TV Show by Date" + - "Only Recent" + + overrides: + tv_show_directory: "/tv_shows/youtube" + + +The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section ` + + +Line 4 begins the definition o your custom ``presets``, with line 5 being the name of your first custom ``preset``. + +Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/guides/getting_started/prebuilt_presets` 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 +- only uploaded in the last 2 months (and will also delete any files in the media library which were uploaded over 2 months ago) + +Line 11 is an override variable, ``tv_show_directory``, that tells ``ytdl-sub`` where to save your downloaded files once they've been processed, also known as the ``output_directory``. In this case, the downloaded files will be saved to the ``youtube`` folder in the root ``tv_shows`` directory. \ No newline at end of file diff --git a/docs/source/guides/getting_started/first_download.rst b/docs/source/guides/getting_started/first_download.rst new file mode 100644 index 00000000..c2a5d2da --- /dev/null +++ b/docs/source/guides/getting_started/first_download.rst @@ -0,0 +1,30 @@ +Initial Download +================ + +Once you have the ``config.yaml`` and ``subscriptions.yaml`` files created and filled out, you can perform your first download. Access ``ytdl-sub``, navigate to the directory containing your ``config.yaml`` and ``subscriptions.yaml`` files, then run the below command: + +.. tab-set:: + + .. tab-item:: Dry run + + 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. + + .. code-block:: shell + + ytdl-sub --dry-run sub + + .. tab-item:: Normal run + + 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``. + + .. code-block:: shell + + ytdl-sub sub + + .. tab-item:: One-time download + + 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 "My Favorite YouTube Channels" --overrides.subscription_name "Rick Astley" --overrides.subscription_value "https://www.youtube.com/@RickAstleyYT/videos" \ 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 a180c6f1..9f5c37c3 100644 --- a/docs/source/guides/getting_started/first_sub.rst +++ b/docs/source/guides/getting_started/first_sub.rst @@ -1,2 +1,13 @@ -Initial Subscriptions -===================== \ No newline at end of file +Initial Subscription +==================== + +Your first subscription should look similar to the below: + +.. code-block:: yaml + + "My Favorite YouTube Channels": + "Rick Astley": "https://www.youtube.com/@RickAstleyYT/videos" + +The first line in this subscription file is the ``preset``, which provides the "definitions" for the subscription as listed in :doc:`/guides/getting_started/first_config`. + +The second line is the actual ``subscription``, named ``Rick Astley``, with a link to a :yt-dlp:`yt-dlp supported site `, in this case a YouTube channel. \ No newline at end of file diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index c9641e63..734482b4 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -1,15 +1,84 @@ Getting Started =============== -Getting started involves a few steps: +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:`prebuilt_presets` don't work for you) +- Create your configuration file (if the :doc:`prebuilt_presets` don't fit your needs) - Create your subscription file - Automate starting YTDL-Sub +Prerequisite Knowledge +---------------------- + +.. _navigate directories: https://en.wikipedia.org/wiki/Cd_(command) +.. _YAML syntax: https://yaml.org/spec/1.2.2/#chapter-2-language-overview + + +In order to use ``ytdl-sub`` in any of the forms listed in these docs, you will need some basic knowledge. + +Be sure that you: + ☑ Can `navigate directories`_ in a command line interface (or CLI) + + ☑ Have a basic understanding of `YAML syntax`_ + +If you plan on using the headless image of ``ytdl-sub``, you: + ☑ Can use ``nano`` or ``vim`` to edit OR + + ☑ Can mount the config directory somewhere you can open it using gui text editors + +Additional useful (but not required) knowledge: + ☑ Understanding how :yt-dlp:`\ ` works + + +Quick Overview of ``ytdl-sub`` +------------------------------ + +``ytdl-sub`` uses two types of YAML files: + +- ``config.yaml`` defines ``presets``, which are the "definitions" of your media. ``presets`` "define" how you want your media downloaded, which formats, naming conventions to follow when saving them, etc. These ``presets`` can also inherit other ``presets``, so that you can easily modify an existing ``preset``. +- ``subscriptions.yaml`` defines ``subscriptions``, which specify the media we want to recurrently download, like YouTube channels and playlists, SoundCloud artists, or any :yt-dlp:`yt-dlp supported site `. ``subscriptions`` use ``presets`` to define how ``ytdl-sub`` should handle downloading, processing, and saving them. + +When ``ytdl-sub`` is run, in its most basic form: + +.. tab-set-code:: + + .. code-block:: shell + + ytdl-sub sub + + .. code-block:: powershell + + ytdl-sub.exe sub + +``ytdl-sub`` initially downloads all files to a defined ``working_directory``. This is a temporary storage spot for metadata and media files so that errors during processing- if they occur- don't affect your existing media library. Once all file processing is complete, your media files are moved to the ``output_directory``. + +Ready to Start? +--------------- + +Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started: + +:doc:`Step 1: Initial Configuration ` + +:doc:`Step 2: Initial Subscriptions ` + +:doc:`Step 3: Your First Download ` + +:doc:`Step 4: Automating Downloads ` + +Other docs that may be of use: + +:doc:`prebuilt_presets` + +:doc:`examples` + .. toctree:: + :hidden: + :caption: Getting Started Guide + :maxdepth: 1 + first_config first_sub + first_download automating_downloads prebuilt_presets examples \ No newline at end of file diff --git a/docs/source/guides/install/docker.rst b/docs/source/guides/install/docker.rst index a0d28445..f7b3d205 100644 --- a/docs/source/guides/install/docker.rst +++ b/docs/source/guides/install/docker.rst @@ -13,15 +13,15 @@ and install ytdl-sub on top. There are two flavors to choose from. For automating ``subscriptions.yaml`` downloads to pull new media, see :doc:`/guides/getting_started/automating_downloads` on how to set up a cron job in any of the docker containers. -GUI -^^^^ +GUI Image +~~~~~~~~~ The GUI image uses LSIO's `code-server `_ for its base image. More info on other code-server environment variables can be found within its documentation. This is the recommended way to use ``ytdl-sub``. -After starting, code-server will be running at http://localhost:8443/ +After starting, code-server will be running at http://localhost:8443/, which is how you will access and interact with ``ytdl-sub``. .. code-block:: yaml @@ -43,8 +43,8 @@ After starting, code-server will be running at http://localhost:8443/ - 8443:8443 restart: unless-stopped -Headless -^^^^^^^^^^ +Headless Image +~~~~~~~~~~~~~~ The headless image uses LSIO's `baseimage-alpine `_ @@ -55,6 +55,8 @@ via exec'ing into the image using the command: docker exec -u abc -it ytdl-sub /bin/bash +This is how you will access and interact with ``ytdl-sub``. + .. code-block:: yaml @@ -76,14 +78,14 @@ via exec'ing into the image using the command: restart: unless-stopped CPU/GPU Passthrough -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ For CPU or GPU passthrough, you must use either the GUI image or the headless Ubuntu image ``ghcr.io/jmbannon/ytdl-sub:ubuntu-latest``. The docker-compose examples use the GUI image. CPU -____ +^^^ .. code-block:: yaml @@ -108,7 +110,7 @@ ____ restart: unless-stopped GPU -____ +^^^ .. code-block:: yaml @@ -138,7 +140,8 @@ ____ restart: unless-stopped Docker CLI --------------- +---------- + .. code-block:: bash docker run -d \ diff --git a/docs/source/guides/install/index.rst b/docs/source/guides/install/index.rst index 935b6ee4..9acbf9df 100644 --- a/docs/source/guides/install/index.rst +++ b/docs/source/guides/install/index.rst @@ -4,6 +4,8 @@ Install by Platform All installations require a 64-bit CPU. 32-bit is not supported. +Once you've completed your installation, please refer to the :doc:`../getting_started/index` guide for next steps + .. toctree:: docker linux diff --git a/docs/source/index.rst b/docs/source/index.rst index 604e0570..af274667 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,9 +7,9 @@ ytdl-sub User Guide guides/index faq/index config - deprecation_notices presets usage + deprecation_notices .. note:: End goal similar to: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html Initial plans: diff --git a/docs/source/presets.rst b/docs/source/presets.rst index b69a019a..10c25b1f 100644 --- a/docs/source/presets.rst +++ b/docs/source/presets.rst @@ -85,15 +85,15 @@ Two main use cases of a collection are: 2. Organize one or more YouTube channels/playlists, where each season represents a separate channel/playlist. -Player Presets -"""""""""""""" +Player Presets 2 +"""""""""""""""" * ``kodi_tv_show_collection`` * ``jellyfin_tv_show_collection`` * ``plex_tv_show_collection`` -Episode Formatting Presets -"""""""""""""""""""""""""" +Episode Formatting Presets 2 +"""""""""""""""""""""""""""" * ``season_by_collection__episode_by_year_month_day`` * ``season_by_collection__episode_by_year_month_day_reversed``