[DOCS] readthedocs makeover (#493)

docs/config.rst

@@ -17,6 +17,10 @@ The ``config.yaml`` is made up of two sections:
 You can jump to any section and subsection of the config using the navigation
 section to the left.
 
+Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``.
+If you wish to represent paths like Windows, you will need to ``C:\\double\\bashslash\\paths``
+in order to escape the backslash character.
+
 configuration
 ^^^^^^^^^^^^^
 The ``configuration`` section contains app-wide configs applied to all presets
@@ -311,51 +315,3 @@ The `config.yaml`_ uses various types for its configurable fields. Below is a de
 .. autoclass:: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator()
 
 .. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesDictFormatterValidator()
-
-Deprecation Updates
--------------------
-
-.. _yt_deprecate:
-
-youtube download strategy
-^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``youtube`` download strategies will be removed in ytdl-sub 0.6 in favor of the
-:ref:`url` download strategy. Update your configs from:
-
-.. code-block:: yaml
-  :caption: deprecated download strategy
-
-   my_subscription_name:
-     youtube:
-       download_strategy: "channel"
-       channel_url: "https://www.youtube.com/c/ProjectZombie603"
-       channel_avatar_path: "poster.jpg"
-       channel_banner_path: "banner.jpg"
-
-to
-
-.. code-block:: yaml
-  :caption: updated download strategy
-
-   my_subscription_name:
-     download:
-       download_strategy: "url"
-       url: "https://www.youtube.com/c/ProjectZombie603"
-       playlist_thumbnails:
-        - name: "poster.jpg"
-          uid: "avatar_uncropped"
-        - name: "banner.jpg"
-          uid: "banner_uncropped"
-
-Despite the longer definition, this more generic download strategy will work
-with any yt-dlp supported site and can better adapt to external changes without
-needing to change the codebase.
-
-.. _sc_deprecate:
-
-soundcloud download strategy
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``soundcloud`` download strategies will be removed in ytdl-sub 0.6 in favor
-of the :ref:`url` download strategy. Refer to the
-`soundcloud discography config <https://github.com/jmbannon/ytdl-sub/blob/master/examples/soundcloud_discography_config.yaml>`_.
-example on how to update.

docs/getting_started.rst

@@ -0,0 +1,29 @@
+Getting Started
+===============
+
+Walk-through Guide
+-------------------
+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.
+
+Example Configs
+---------------
+If you are ready to start downloading, see our
+`examples directory <https://github.com/jmbannon/ytdl-sub/tree/master/examples>`_
+for ready-to-use configs and subscriptions. Read through them carefully before use.
+
+Using Example Configs
+^^^^^^^^^^^^^^^^^^^^^^
+Copy and paste the examples into local yaml files, modify the
+``working_directory`` and ``output_directory`` with your desired paths,
+and perform a dry-run using
+
+.. code-block:: bash
+
+   ytdl-sub \
+     --dry-run \
+     --config path/to/config.yaml \
+     sub path/to/subscriptions.yaml
+
+This will simulate what a download will look like.

docs/index.rst

@@ -22,5 +22,7 @@ Contents
    :maxdepth: 2
 
    install
+   usage
+   getting_started
    presets
    config

docs/install.rst

@@ -140,7 +140,7 @@ With a Python 3.10 virtual environment, you can clone and install the repo using
    pip install -e .
 
 Local Docker Build
---------------
+-------------------
 Run ``make docker`` in the root directory of this repo to build the image. This
 will build the python wheel and install it in the Dockerfile.
 

docs/usage.rst

@@ -0,0 +1,74 @@
+Usage
+=======
+
+.. code-block::
+
+   ytdl-sub [GENERAL OPTIONS] {sub,dl,view} [COMMAND OPTIONS]
+
+For Windows users, it would be ``ytdl-sub.exe``
+
+General Options
+---------------
+
+General options must be specified before the command (i.e. ``sub``).
+
+.. code-block:: text
+
+  -h, --help            show this help message and exit
+  -c CONFIGPATH, --config CONFIGPATH
+                        path to the config yaml, uses config.yaml if not provided
+  --dry-run             preview what a download would output, does not perform any
+                        video downloads or writes to output directories
+  --log-level quiet|info|verbose|debug
+                        level of logs to print to console, defaults to info
+
+Sub Options
+-----------
+Download all subscriptions specified in each ``SUBPATH``.
+
+.. code-block::
+
+   ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
+
+``SUBPATH`` is one or more paths to subscription files, uses ``subscriptions.yaml`` if not provided.
+It will use the config specified by ``--config``, or ``config.yaml`` if not provided.
+
+Download Options
+-----------------
+Download a single subscription in the form of CLI arguments.
+
+.. code-block::
+
+   ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]
+
+``SUBSCRIPTION ARGUMENTS`` are exactly the same as YAML arguments, but use periods (``.``) instead
+of indents for specifying YAML from the CLI. For example, you can represent this subscription:
+
+.. code-block:: yaml
+
+   rick_a:
+     preset:
+       - "tv_show"
+     overrides:
+       tv_show_name: "Rick A"
+       url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
+
+Using the command:
+
+.. code-block:: bash
+
+   ytdl-sub dl \
+       --preset "tv_show" \
+       --overrides.tv_show_name "Rick A" \
+       --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
+
+See how to shorten commands using
+`download aliases <https://ytdl-sub.readthedocs.io/en/latest/config.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
+
+View Options
+-----------------
+.. code-block::
+
+   ytdl-sub view [URL]
+
+Preview the source variables for a given URL. Helps when creating new configs.

src/ytdl_sub/cli/main_args_parser.py

@@ -36,7 +36,8 @@ parser.add_argument(
 parser.add_argument(
     MainArgs.DRY_RUN.value,
     action="store_true",
-    help="does not perform any video downloads or writes to output directories",
+    help="preview what a download would output, "
+    "does not perform any video downloads or writes to output directories",
 )
 parser.add_argument(
     MainArgs.LOG_LEVEL.value,

src/ytdl_sub/config/config_validator.py

@@ -66,6 +66,8 @@ class ConfigOptions(StrictDictValidator):
     @property
     def dl_aliases(self) -> Optional[Dict[str, str]]:
         """
+        .. _dl_aliases:
+
         Optional. Alias definitions to shorten ``ytdl-sub dl`` arguments. For example,
 
         .. code-block:: yaml