docs docs more docs

docs/conf.py

@@ -61,3 +61,7 @@ add_module_names = False
 python_use_unqualified_type_names = False
 napoleon_numpy_docstrings = True
 napoleon_use_rtype = False
+
+# -- Options for autodocs -------------------------------------------------
+
+autodoc_default_options = {"autodoc_typehints_format": "short"}

docs/config.rst

@@ -4,6 +4,9 @@ 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.
 
+config.yaml
+-----------
+
 The ``config.yaml`` is made up of two sections:
 
 .. code-block:: yaml
@@ -15,28 +18,28 @@ 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
 and subscriptions.
 
 presets
--------
+^^^^^^^
 ``presets`` define a `formula` for how to format downloaded media and metadata.
 
 download_strategy
-^^^^^^^^^^^^^^^^^
+"""""""""""""""""
 Download strategies dictate what is getting downloaded from a source. Each
 download strategy has its own set of parameters.
 
 youtube
-"""""""
+'''''''
 Download strategies for downloading videos (or audio if you configure `ytdl_options`_ correctly) from Youtube. See
 Download strategies for downloading music from Soundcloud. See
 :class:`Youtube Variables <ytdl_sub.entries.variables.youtube_variables>`
 for available source variables to use.
 
 channel
-'''''''
+_______
 .. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubeChannelDownloaderOptions()
   :members:
   :member-order: bysource
@@ -46,7 +49,7 @@ channel
 -------------------------------------------------------------------------------
 
 playlist
-''''''''
+________
 .. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubePlaylistDownloaderOptions()
   :members:
   :member-order: bysource
@@ -55,7 +58,7 @@ playlist
 -------------------------------------------------------------------------------
 
 video
-'''''
+_____
 .. autoclass:: ytdl_sub.downloaders.youtube_downloader.YoutubeVideoDownloaderOptions()
   :members:
   :member-order: bysource
@@ -64,13 +67,13 @@ video
 -------------------------------------------------------------------------------
 
 soundcloud
-""""""""""
+''''''''''
 Download strategies for downloading music from Soundcloud. See
 :class:`Soundcloud Variables <ytdl_sub.entries.variables.soundcloud_variables>`
 for available source variables to use.
 
 albums_and_singles
-''''''''''''''''''
+__________________
 .. autoclass:: ytdl_sub.downloaders.soundcloud_downloader.SoundcloudAlbumsAndSinglesDownloadOptions()
   :members:
   :member-order: bysource
@@ -79,7 +82,7 @@ albums_and_singles
 -------------------------------------------------------------------------------
 
 output_options
-^^^^^^^^^^^^^^
+""""""""""""""
 
 .. autoclass:: ytdl_sub.config.preset_options.OutputOptions()
   :members:
@@ -88,38 +91,55 @@ output_options
 -------------------------------------------------------------------------------
 
 ytdl_options
-^^^^^^^^^^^^
+""""""""""""
 .. autoclass:: ytdl_sub.config.preset_options.YTDLOptions()
 
 -------------------------------------------------------------------------------
 
+.. _overrides:
+
 overrides
-^^^^^^^^^
+"""""""""
 .. autoclass:: ytdl_sub.config.preset_options.Overrides()
 
+-------------------------------------------------------------------------------
+
+
 Plugins
-^^^^^^^
+"""""""
 Plugins are used to perform any type of post-processing to the already downloaded files.
 
 music_tags
-""""""""""
+''''''''''
 .. autoclass:: ytdl_sub.plugins.music_tags.MusicTagsOptions()
   :members:
 
+-------------------------------------------------------------------------------
+
 nfo
-"""
+'''
 .. autoclass:: ytdl_sub.plugins.nfo_tags.NfoTagsOptions()
   :members:
   :member-order: bysource
 
+-------------------------------------------------------------------------------
+
 nfo_output_directory
-""""""""""""""""""""
+''''''''''''''''''''
 .. autoclass:: ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions()
+  :members:
+  :member-order: bysource
+
+-------------------------------------------------------------------------------
+
+.. _source-variables:
 
 Source Variables
 ----------------
-Source variables are ``{variables}`` that contain metadata from downloaded media.
+
-These variables can be used in StringFormatters, but not OverrideFormatters.
+.. autoclass:: ytdl_sub.entries.variables.entry_variables.SourceVariables
+
+.. _youtube-variables:
 
 Youtube Variables
 ^^^^^^^^^^^^^^^^^
@@ -128,6 +148,8 @@ Youtube Variables
    :inherited-members:
    :undoc-members:
 
+.. _soundcloud-variables:
+
 Soundcloud Variables
 ^^^^^^^^^^^^^^^^^^^^
 .. automodule:: ytdl_sub.entries.variables.soundcloud_variables
@@ -135,16 +157,18 @@ Soundcloud Variables
    :inherited-members:
    :undoc-members:
 
-Formatters
+-------------------------------------------------------------------------------
-----------
+
-Formatters are strings that can contain ``{variables}`` that are overwritten at
+Config Types
-run-time with values assigned to that variable. There are two different types of
+------------
-formatters.
+The `config.yaml`_ uses various types for its configurable fields. Below is a definition for each type.
 
-String Formatter
-^^^^^^^^^^^^^^^^
 .. autoclass:: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator()
 
-Overrides Formatter
-^^^^^^^^^^^^^^^^^^^
 .. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator()
+
+.. autoclass:: ytdl_sub.validators.string_datetime.StringDatetimeValidator()
+
+.. autoclass:: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator()
+
+.. autoclass:: ytdl_sub.validators.string_formatter_validators.OverridesDictFormatterValidator()

docs/index.rst

@@ -2,20 +2,20 @@ ytdl-sub: to enjoy media in your favorite player
 ================================================
 
 ytdl-sub is an `open-source <https://github.com/jmbannon/ytdl-sub>`_
-python app that strives to automate downloading media and preparing it for
+python app that automates downloading media and preparing it for
 consumption in your favorite media player in the most hassle-free way
 possible.
 
 If you are new to ytdl-sub, head over to the
 :doc:`Getting Started <getting_started>`
-page. This guide shows how you can install ytdl-sub, configure it to download
+page. This guide explains how you can use ytdl-sub, install, configure it to download
 various types of media, and start downloading.
 
 Contents
 ========
 
 .. toctree::
-   :maxdepth: 10
+   :maxdepth: 2
 
    getting_started
    config

src/ytdl_sub/entries/variables/entry_variables.py

@@ -9,9 +9,13 @@ from ytdl_sub.entries.base_entry import BaseEntry
 # pylint: disable=no-member
 
 
-class BaseEntryVariables:
+class SourceVariables:
     """
-    Abstract entry object to represent usable variables for formatting presets and subscriptions
+    Source variables are ``{variables}`` that contain metadata from downloaded media.
+    These variables can be used with fields that expect
+    :class:`~ytdl_sub.validators.string_formatter_validators.StringFormatterValidator`,
+    but not
+    :class:`~ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator`.
     """
 
     @property
@@ -45,7 +49,7 @@ class BaseEntryVariables:
         return {property_name: getattr(self, property_name) for property_name in property_names}
 
 
-class EntryVariables(BaseEntryVariables):
+class EntryVariables(SourceVariables):
     @property
     def title(self: BaseEntry) -> str:
         """

src/ytdl_sub/validators/string_formatter_validators.py

@@ -13,7 +13,28 @@ from ytdl_sub.validators.validators import Validator
 
 class StringFormatterValidator(Validator):
     """
-    Ensures user-created formatter strings are valid
+    String that can use
+    :class:`source variables <ytdl_sub.entries.variables.entry_variables.SourceVariables>`
+    and
+    :class:`overrides <ytdl_sub.config.preset_options.Overrides>`
+    for populating things like file paths and metadata.
+
+    .. code-block:: python
+
+       "{tv_show_file_name}.s{upload_year}.e{upload_month}{upload_day_padded}.{ext}"
+
+    is valid when using
+    :class:`youtube variables <ytdl_sub.entries.variables.youtube_variables.YoutubeVideoVariables>`
+    with the following overrides:
+
+    .. code-block:: yaml
+
+       presets:
+         my_example_preset:
+           overrides:
+             tv_show_file_name: "sweet_tv_show"
+
+    and would resolve to something like ``sweet_tv_show.s2022.e502.mp4``.
     """
 
     _expected_value_type = str
@@ -132,12 +153,22 @@ class StringFormatterValidator(Validator):
         return formatter.format_string
 
 
+# pylint: disable=line-too-long
 class OverridesStringFormatterValidator(StringFormatterValidator):
     """
-    A string formatter that should strictly use overrides that resolve without any entry variables.
+    String that can `only` use :class:`overrides <ytdl_sub.config.preset_options.Overrides>`.
+
+    Used in fields that do not touch the downloaded files themselves, but instead, `single`
+    things like
+    :func:`output_directory <ytdl_sub.config.preset_options.OutputOptions.output_directory>`
+    or the fields in
+    :class:`nfo_output_directory <ytdl_sub.plugins.output_directory_nfo_tags.OutputDirectoryNfoTagsOptions>`
     """
 
 
+# pylint: enable=line-too-long
+
+
 class DictFormatterValidator(LiteralDictValidator):
     """
     Validates a dictionary made up of key: string_formatters