Moving cron setup and intro to ytdl-sub from GH

docs/source/conf.py

@@ -6,23 +6,24 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'ytdl-sub'
+project = "ytdl-sub"
-copyright = '2023, Jesse Bannon'
+copyright = "2023, Jesse Bannon"
-author = 'Jesse Bannon'
+author = "Jesse Bannon"
-release = '2023.12.15'
+release = "2023.12.15"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.autodoc",
-    ]
+    "sphinx_copybutton",
+    "sphinx_design",
+]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -48,12 +49,5 @@ html_theme_options = {
     ),
 }
 
-html_sidebars ={
-    # "**": [
-        # "globaltoc.html",
-        # "sourcelink.html",
-        # "searchbox.html"
-    # ],
-}
 
-html_static_path = ['_static']
+html_static_path = ["_static"]

docs/source/faq/index.rst

@@ -0,0 +1,59 @@
+FAQ
+===
+
+Since ytdl-sub is relatively new to the public, there has not been many question asked yet. We will update this as
+more questions get asked.
+
+.. contents:: Frequently Asked Questions
+  :depth: 3
+
+How do I...
+-----------
+
+...download age-restricted YouTube videos?
+''''''''''''''''''''''''''''''''''''''''''
+See
+`ytdls recommended way <https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl>`_
+to download your YouTube cookie, then add it to your
+`ytdl options <https://ytdl-sub.readthedocs.io/en/latest/config.html#ytdl-options>`_ section of your config:
+
+.. code-block:: yaml
+
+   ytdl_options:
+     cookiefile: "/path/to/cookies/file.txt"
+
+...automate my downloads?
+'''''''''''''''''''''''''
+`This part of the wiki <https://github.com/jmbannon/ytdl-sub/wiki/7.-Automate-Downloading-New-Content-Using-Your-Configs>`_ shows how to set up ``ytdl-sub`` to run in a cron job within Docker.
+
+There is a bug where...
+-----------------------
+
+...date_range is not downloading older videos after I changed the range
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+Your preset most likely has ``break_on_existing`` set to True, which will stop downloading additional metadata/videos if the video exists in your download archive. Set the following in your config to skip downloading videos that exist instead of stopping altogether.
+
+.. code-block:: yaml
+
+   ytdl_options:
+     break_on_existing: False
+
+After your download your new date_range duration, re-enable ``break_on_existing`` to speed up successive downloads.
+
+...it is downloading non-English title and description metadata
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+Most likely the video has a non-English language set to its 'native' language. You can tell yt-dlp to explicitly download English metadata using
+
+.. code-block:: yaml
+
+   ytdl_options:
+     extractor_args:
+       youtube:
+         lang:
+           - "en"
+
+...Plex is not showing my TV shows correctly
+''''''''''''''''''''''''''''''''''''''''''''
+Set the following
+`Scanner and Agent <https://i.imgur.com/zdZhCLZ.png>`_
+for your library.

docs/source/guides/getting_started/automating_downloads.rst

@@ -0,0 +1,131 @@
+Automating Downloads
+====================
+
+:ref:`docker-unraid-setup`
+
+:ref:`linux-setup`
+
+:ref:`windows-setup`
+
+.. _cron tab manpage: https://man7.org/linux/man-pages/man5/crontab.5.html#EXAMPLE_CRON_FILE
+
+.. _docker-unraid-setup:
+
+Docker and Unraid
+-----------------
+
+.. tab-set::
+    
+    .. tab-item:: GUI Image
+        
+        The script that will execute automatically is located at ``/config/ytdl-sub-configs/run-cron``. 
+
+        Access your container at http://localhost:8443/, then in the GUI terminal run these commands:
+
+        .. code-block:: shell
+
+            echo '#!/bin/bash' > /config/ytdl-sub-configs/run_cron
+            echo "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" >> /config/ytdl-sub-configs/run_cron
+            echo "echo 'Cron started, running ytdl-sub...'" >> /config/ytdl-sub-configs/run_cron
+            echo "cd /config/ytdl-sub-configs" >> /config/ytdl-sub-configs/run_cron
+            echo "ytdl-sub --config=config.yaml sub subscriptions.yaml" >> /config/ytdl-sub-configs/run_cron
+            chmod +x /config/ytdl-sub-configs/run_cron
+            chown abc:abc /config/ytdl-sub-configs/run_cron
+
+        You can test the newly created script by running: 
+
+        .. code-block:: shell
+
+            /config/ytdl-sub-configs/run_cron
+
+        To create the cron definition, run the following command:
+
+        .. code-block:: shell
+
+            echo "# min   hour    day     month   weekday command" > /config/crontabs/abc
+            echo "  0     */6     *       *       *       /config/ytdl-sub-configs/run_cron" >> /config/crontabs/abc
+
+        This will run the script every 6 hours. To run every hour, change ``*/6`` to ``*/1``, or to run once a day, change the same value to the hour (in 24hr format) that you want it to run at. See the `cron tab manpage`_ for more options.
+
+    .. tab-item:: Headless Image
+
+        .. _LinuxServer's Universal Cron mod: https://github.com/linuxserver/docker-mods/tree/universal-cron
+
+        The first step is to ensure you have `LinuxServer's Universal Cron mod`_ enabled via the environment variable. For the GUI image, this is already included (no need to add it).
+
+        .. code-block:: yaml
+
+            services:
+                ytdl-sub:
+                    image: ghcr.io/jmbannon/ytdl-sub:latest
+                    container_name: ytdl-sub
+                    environment:
+                        - PUID=1000
+                        - PGID=1000
+                        - TZ=America/Los_Angeles
+                        - DOCKER_MODS=linuxserver/mods:universal-cron  # <-- Make sure you have this!
+                    volumes:
+                        # ensure directories have user permissions
+                        - </path/to/ytdl-sub/config>:/config
+                        - </path/to/ytdl-sub/tv_shows>:/tv_shows
+                    restart: unless-stopped
+
+        This line will tell your container to install and enable cron on start.
+
+        If you had to add this line, you will need to restart your container.
+
+        .. code-block:: shell
+
+            docker compose restart
+
+        The script that will execute automatically is located at ``/config/run-cron``. 
+
+        Access your container from the terminal by running:
+
+        .. code-block:: shell
+
+            docker exec -itu abc ytdl-sub /bin/bash
+
+        then in the terminal run these commands:
+
+        .. code-block:: shell
+
+            echo '#!/bin/bash' > /config/ytdl-sub-configs/run_cron
+            echo "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" >> /config/ytdl-sub-configs/run_cron
+            echo "echo 'Cron started, running ytdl-sub...'" >> /config/ytdl-sub-configs/run_cron
+            echo "cd /config/ytdl-sub-configs" >> /config/ytdl-sub-configs/run_cron
+            echo "ytdl-sub --config=config.yaml sub subscriptions.yaml" >> /config/ytdl-sub-configs/run_cron
+            chmod +x /config/ytdl-sub-configs/run_cron
+            chown abc:abc /config/ytdl-sub-configs/run_cron
+
+        You can test the newly created script by running: 
+
+        .. code-block:: 
+
+            /config/run_cron
+
+        To create the cron definition, run the following command:
+
+        .. code-block:: shell
+
+            echo "# min   hour    day     month   weekday command" > /config/crontabs/abc
+            echo "  0     */6     *       *       *       /config/run_cron" >> /config/crontabs/abc
+        
+        This will run the script every 6 hours. To run every hour, change ``*/6`` to ``*/1``, or to run once a day, change the same value to the hour (in 24hr format) that you want it to run at. See the `cron tab manpage`_ for more options.
+
+.. _linux-setup:
+
+Linux 
+-----
+
+
+
+.. _windows-setup:
+
+Windows
+-------
+To be tested (please contact code owner or join the discord server if you can test this out for us)
+
+.. code-block:: powershell
+
+    ytdl-sub.exe --config \path\to\config\config.yaml sub \path\to\config\subscriptions.yaml

docs/source/guides/getting_started/first_config.rst

@@ -0,0 +1,2 @@
+Initial Configuration
+=====================

docs/source/guides/getting_started/first_sub.rst

@@ -0,0 +1,2 @@
+Initial Subscriptions
+=====================

docs/source/guides/getting_started/index.rst

@@ -1,7 +1,15 @@
 Getting Started
 ===============
 
+Getting started involves a few steps:
+
+- Create your configuration file (if the :doc:`prebuilt_presets` don't work for you)
+- Create your subscription file
+- Automate starting YTDL-Sub
+
 .. toctree::
-    initial_setup
+    first_config
+    first_sub
+    automating_downloads
     prebuilt_presets
     examples

docs/source/guides/getting_started/initial_setup.rst

@@ -1,5 +0,0 @@
-Initial Setup
-=============
-If you haven't read it yet, it's highly recommended to go through our
-`walk-through guide <https://github.com/jmbannon/ytdl-sub/wiki/1.-Introduction>`_
-to get familiar with how ``ytdl-sub`` works.

docs/source/guides/install/docker.rst

@@ -1,15 +1,17 @@
 Docker
 ======
 
+
 Docker Compose
 --------------
+.. _LSIO-based images: https://www.linuxserver.io/
+
 The ytdl-sub Docker images use
-`LSIO-based images <https://www.linuxserver.io/>`_
+`LSIO-based images`_
-and installs ytdl-sub on top. There are a few flavors to choose from.
+and install ytdl-sub on top. There are two flavors to choose from.
 
 For automating ``subscriptions.yaml`` downloads to pull new media, see
-`this guide <https://github.com/jmbannon/ytdl-sub/wiki/7.-Automate-Downloading-New-Content-Using-Your-Configs/>`_
+:doc:`/guides/getting_started/automating_downloads` on how to set up a cron job in any of the docker containers.
-on how set up a cron job in any of the docker containers.
 
 GUI
 ^^^^

docs/source/guides/install/unraid.rst

@@ -1,5 +1,3 @@
 Unraid
 --------------
-See the
+See the `community app <https://unraid.net/community/apps?q=ytdl-sub#r>`_ ``ytdl-sub``. Uses Docker under the hood.
-`community app <https://unraid.net/community/apps?q=ytdl-sub#r>`_
-``ytdl-sub``. Uses Docker under the hood.

docs/source/index.rst

@@ -1,21 +1,19 @@
-.. ytdl-sub documentation master file, created by
+ytdl-sub User Guide
-   sphinx-quickstart on Fri Dec 15 21:08:10 2023.
+===================
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to ytdl-sub's documentation!
-====================================
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
+   introduction
    guides/index
+   faq/index
    config
    deprecation_notices
    presets
    usage
 
-.. note:: End goal: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html
+.. 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

docs/source/introduction.rst

@@ -0,0 +1,38 @@
+What is ytdl-sub?
+=================
+
+.. _yt-dlp: https://github.com/yt-dlp/yt-dlp
+.. _kodi: https://github.com/xbmc/xbmc
+.. _jellyfin: https://github.com/jellyfin/jellyfin
+.. _plex: https://github.com/plexinc/pms-docker
+.. _emby: https://github.com/plexinc/pms-docker
+
+``ytdl-sub`` is a command-line tool that downloads media via `yt-dlp`_ and prepares it for your favorite media player (`Kodi`_, `Jellyfin`_, `Plex`_, `Emby`_, modern music players).
+
+Visual examples
+---------------
+
+.. figure:: https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG
+
+    Youtube channels as TV shows in Jellyfin
+
+.. figure:: https://user-images.githubusercontent.com/10107080/182677256-43aeb029-0c3f-4648-9fd2-352b9666b262.PNG
+
+    Music videos and concerts in Jellyfin
+
+.. figure:: https://user-images.githubusercontent.com/10107080/182677268-d1bf2ff0-9b9c-4a04-98ec-443a67ada734.png
+
+    Music videos and concerts in Kodi
+
+.. figure:: https://user-images.githubusercontent.com/10107080/182685415-06adf477-3dd3-475d-bbcd-53b0152b9f0a.PNG
+
+    SoundCloud albums and singles in MusicBee
+
+
+Why ytdl-sub?
+-------------
+There is a lack of open-source tools to download media and generate metadata to play it in these players. Most solutions involve using multiple tools or bash scripts to achieve this. ``ytdl-sub`` aims to consolidate all of this logic into a single easy-to-use application that can run automatically once configured.
+
+Why download instead of stream?
+-------------------------------
+We believe it is important to download what you like because there is no guarantee it will stay online forever. We also believe it is important to download it in such a way that it is easy to consume. Most solutions today force you to watch/listen to your downloaded content via file system or web browser. ``ytdl-sub`` aims to format downloaded content for any media player.