From 6146762571922cbbfd05031969aa794aeb02cefe Mon Sep 17 00:00:00 2001 From: Jesse Bannon Date: Wed, 1 Mar 2023 23:45:16 -0800 Subject: [PATCH] [DOCS] readthedocs makeover (#493) --- docs/config.rst | 52 ++--------------- docs/getting_started.rst | 29 ++++++++++ docs/index.rst | 2 + docs/install.rst | 2 +- docs/usage.rst | 74 +++++++++++++++++++++++++ src/ytdl_sub/cli/main_args_parser.py | 3 +- src/ytdl_sub/config/config_validator.py | 2 + 7 files changed, 114 insertions(+), 50 deletions(-) create mode 100644 docs/getting_started.rst create mode 100644 docs/usage.rst diff --git a/docs/config.rst b/docs/config.rst index 21385dda4..4e3325a0c 100644 --- a/docs/config.rst +++ b/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 `_. -example on how to update. diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 000000000..8e1d449f8 --- /dev/null +++ b/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 `_ +to get familiar with how ``ytdl-sub`` works. + +Example Configs +--------------- +If you are ready to start downloading, see our +`examples directory `_ +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. diff --git a/docs/index.rst b/docs/index.rst index 8ee85a758..7974add8f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,5 +22,7 @@ Contents :maxdepth: 2 install + usage + getting_started presets config diff --git a/docs/install.rst b/docs/install.rst index d35979737..10553b382 100644 --- a/docs/install.rst +++ b/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. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 000000000..942bd5d40 --- /dev/null +++ b/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 `_. + +View Options +----------------- +.. code-block:: + + ytdl-sub view [URL] + +Preview the source variables for a given URL. Helps when creating new configs. diff --git a/src/ytdl_sub/cli/main_args_parser.py b/src/ytdl_sub/cli/main_args_parser.py index c77d354f6..0c9eb2958 100644 --- a/src/ytdl_sub/cli/main_args_parser.py +++ b/src/ytdl_sub/cli/main_args_parser.py @@ -36,7 +36,8 @@ def all(cls) -> List[str]: 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, diff --git a/src/ytdl_sub/config/config_validator.py b/src/ytdl_sub/config/config_validator.py index b5d53586a..255000e2d 100644 --- a/src/ytdl_sub/config/config_validator.py +++ b/src/ytdl_sub/config/config_validator.py @@ -66,6 +66,8 @@ def umask(self) -> Optional[str]: @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