done for now

docs/config.rst

@@ -1,28 +1,32 @@
 Config
 ======
-ytdl-sub is configured in the ``config.yaml`` and consists of two sections:
+ytdl-sub is configured using a ``config.yaml`` file. You can view our
+:doc:`examples <examples>` and read detailed documentation for every configurable
+field below.
+
+The ``config.yaml`` is made up of two sections:
 
 .. code-block:: yaml
 
    configuration:
    presets:
 
+You can jump to any section and subsection of the config using the navigation
+section to the left.
 
 configuration
 -------------
-
+The ``configuration`` section contains app-wide configs applied to all presets
-The ``configuration`` section contains app-wide configs.
+and subscriptions.
 
 presets
 -------
-
 ``presets`` define a `formula` for how to format downloaded media and metadata.
 
-download strategy
+download_strategy
 ^^^^^^^^^^^^^^^^^
-Download strategies dictate what exactly is getting downloaded from which
+Download strategies dictate what is getting downloaded from a source. Each
-source. By having separate strategies, we can define strategy-dependent
+download strategy has its own set of parameters.
-parameters to better fine-tune how we download things.
 
 youtube
 """""""
@@ -56,7 +60,7 @@ after
 _____
   .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubeChannelDownloaderOptions.after
 
---------
+-------------------------------------------------------------------------------
 
 playlist
 ''''''''
@@ -71,7 +75,7 @@ playlist_id
 ___________
   .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubePlaylistDownloaderOptions.playlist_id
 
---------
+-------------------------------------------------------------------------------
 
 video
 '''''
@@ -86,7 +90,7 @@ video_id
 ________
   .. autoproperty:: ytdl_sub.downloaders.youtube_downloader.YoutubeVideoDownloaderOptions.video_id
 
---------
+-------------------------------------------------------------------------------
 
 soundcloud
 """"""""""
@@ -108,7 +112,7 @@ skip_premiere_tracks
 ____________________
   .. autoproperty:: ytdl_sub.downloaders.soundcloud_downloader.SoundcloudAlbumsAndSinglesDownloadOptions.skip_premiere_tracks
 
---------
+-------------------------------------------------------------------------------
 
 output_options
 ^^^^^^^^^^^^^^
@@ -133,40 +137,40 @@ keep_files
 """"""""""
   .. autoproperty:: ytdl_sub.config.preset_options.OutputOptions.keep_files
 
+-------------------------------------------------------------------------------
+
 ytdl_options
 ^^^^^^^^^^^^
-.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions
+.. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
+
+-------------------------------------------------------------------------------
 
 overrides
 ^^^^^^^^^
-.. autoclass:: ytdl_sub.config.preset_options.Overrides
+.. autoclass:: ytdl_sub.config.preset_options.Overrides()
 
 Plugins
 ^^^^^^^
 
 music_tags
 """"""""""
-TODO
+.. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
 
 nfo
 """
-TODO
+.. autoclass:: ytdl_sub.plugins.nfo_tags.NfoTagsOptions()
 
 nfo_output_directory
 """"""""""""""""""""
-TODO
+.. autoclass:: ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions()
 
-Format Variables
+Source Variables
 ----------------
-Format variables are ``{variables}`` that contain metadata from downloaded
+Source variables are ``{variables}`` that contain metadata from downloaded media.
-media.
+These variables can be used in StringFormatters, but not OverrideFormatters.
-
-.. contents:: Source Format Variables
-   :local:
 
 Youtube Variables
 ^^^^^^^^^^^^^^^^^
-
 .. automodule:: ytdl_sub.entries.variables.youtube_variables
    :members:
    :inherited-members:
@@ -174,8 +178,21 @@ Youtube Variables
 
 Soundcloud Variables
 ^^^^^^^^^^^^^^^^^^^^
-
 .. automodule:: ytdl_sub.entries.variables.soundcloud_variables
    :members:
    :inherited-members:
    :undoc-members:
+
+Formatters
+----------
+Formatters are strings that can contain ``{variables}`` that are overwritten at
+run-time with values assigned to that variable. There are two different types of
+formatters.
+
+String Formatter
+^^^^^^^^^^^^^^^^
+.. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator()
+
+Overrides Formatter
+^^^^^^^^^^^^^^^^^^^
+.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator()

src/ytdl_sub/config/preset_options.py

@@ -13,12 +13,52 @@ from ytdl_sub.validators.validators import LiteralDictValidator
 
 
 class YTDLOptions(LiteralDictValidator):
-    """Ensures `ytdl_options` is a dict"""
+    """
+    Optional. This section allows you to add any ytdl argument to ytdl-sub's downloader.
+    The argument names can differ slightly from the command-line argument names. See
+    `this docstring <https://github.com/yt-dlp/yt-dlp/blob/2022.04.08/yt_dlp/YoutubeDL.py#L197>`_
+    for more details.
+
+    ytdl_options should be formatted like:
+
+    .. code-block:: yaml
+
+           presets:
+             my_example_preset:
+               ytdl_options:
+                 ignoreerrors: True
+
+    where each key is a ytdl argument.
+    """
 
 
+# Disable for proper docstring formatting
+# pylint: disable=line-too-long
 class Overrides(DictFormatterValidator):
-    """Ensures `overrides` is a dict"""
+    """
+    Optional. This section allows you to define variables that can be used in any string formatter.
+    For example, if you want your file and thumbnail files to match without copy-pasting a large
+    format string, you can define something like:
 
+    .. code-block:: yaml
+
+       presets:
+         my_example_preset:
+           overrides:
+             output_directory: "/path/to/media"
+             custom_file_name: "{upload_year}.{upload_month_padded}.{upload_day_padded}.{sanitized_title}"
+
+           # Then use the override variables in the output options
+           output_options:
+             output_directory: "{output_directory}"
+             file_name: "{custom_file_name}.{ext}"
+             thumbnail_name: "{custom_file_name}.{thumbnail_ext}"
+
+    Override variables can contain explicit values and other variables, including both override
+    and source variables.
+    """
+
+    # pylint: enable=line-too-long
     def __init__(self, name, value):
         super().__init__(name, value)
         for key in self._keys:
@@ -132,19 +172,23 @@ class OutputOptions(StrictDictValidator):
 
         .. code-block:: yaml
 
-           output_options:
+           presets:
-             keep_files:
+             my_example_preset:
-               before:
+               output_options:
-               after:
+                 keep_files:
+                   before:
+                   after:
 
         where ``before`` and ``after`` are date-times. A common usage of this option is to only
         fill in the after, such as:
 
         .. code-block:: yaml
 
-           output_options:
+           presets:
-             keep_files:
+             my_example_preset:
-               after: today-2weeks
+               output_options:
+                 keep_files:
+                   after: today-2weeks
 
         Which translates to 'keep files uploaded in the last two weeks'.