Migrating GH walkthrough to rtd

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 <a href='~/build/index.html'>beautiful subscriptions</a> is now live"
+        "Migration to <a href='https://ytdl-sub--841.org.readthedocs.build/en/841/config.html#beautifying-subscriptions'>beautiful subscriptions</a> 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")}

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,

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:

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 <guides/getting_started/automating_downloads:docker and unraid>`
+
+:ref:`Guide for Linux <guides/getting_started/automating_downloads:linux>`
+
+:ref:`Guide for Windows <guides/getting_started/automating_downloads: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:

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 <guides/getting_started/index:quick overview of \`\`ytdl-sub\`\`>`
+
+
+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.

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"

docs/source/guides/getting_started/first_sub.rst

@@ -1,2 +1,13 @@
-Initial Subscriptions
+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 <blob/master/supportedsites.md>`, in this case a YouTube channel.

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 <blob/master/supportedsites.md>`. ``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 <first_config>`
+
+:doc:`Step 2: Initial Subscriptions <first_sub>`
+
+:doc:`Step 3: Your First Download <first_download>`
+
+:doc:`Step 4: Automating Downloads <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

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 <https://hub.docker.com/r/linuxserver/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 <https://github.com/linuxserver/docker-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 \

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

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:

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``