From 20d376b5a114dd4f7aa0340e5e17b3dd2283adc7 Mon Sep 17 00:00:00 2001 From: jbannon Date: Tue, 10 May 2022 23:12:53 +0000 Subject: [PATCH] docs docs more docs --- docs/conf.py | 4 + docs/config.rst | 78 ++++++++++++------- docs/index.rst | 6 +- .../entries/variables/entry_variables.py | 10 ++- .../validators/string_formatter_validators.py | 35 ++++++++- 5 files changed, 98 insertions(+), 35 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d603eaa7..47a478be 100644 --- a/docs/conf.py +++ b/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"} diff --git a/docs/config.rst b/docs/config.rst index 7fe369be..1d31a536 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -4,6 +4,9 @@ ytdl-sub is configured using a ``config.yaml`` file. You can view our :doc:`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 ` 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 ` 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 -run-time with values assigned to that variable. There are two different types of -formatters. +------------------------------------------------------------------------------- + +Config Types +------------ +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() \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 8b3be2de..5c7b5e4b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,20 +2,20 @@ ytdl-sub: to enjoy media in your favorite player ================================================ ytdl-sub is an `open-source `_ -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 ` -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 diff --git a/src/ytdl_sub/entries/variables/entry_variables.py b/src/ytdl_sub/entries/variables/entry_variables.py index 6ddc7a75..5e79bc00 100644 --- a/src/ytdl_sub/entries/variables/entry_variables.py +++ b/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: """ diff --git a/src/ytdl_sub/validators/string_formatter_validators.py b/src/ytdl_sub/validators/string_formatter_validators.py index e1b7df97..bc9ba620 100644 --- a/src/ytdl_sub/validators/string_formatter_validators.py +++ b/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 ` + and + :class:`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 ` + 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 `. + + Used in fields that do not touch the downloaded files themselves, but instead, `single` + things like + :func:`output_directory ` + or the fields in + :class:`nfo_output_directory ` """ +# pylint: enable=line-too-long + + class DictFormatterValidator(LiteralDictValidator): """ Validates a dictionary made up of key: string_formatters