321556ecf7
* ci(docs): RTD Sphinx warnings false successes Use the same options on readthedocs.com that we use locally to fail on all warnings, mostly to better catch stale cross references. * docs(usage): Yet another stale Sphinx cross ref I confirmed the previous RTD CI fix in the previous commit by pushing it to a draft PR before pushing this change and the RTD action failed with the warning this commit fixes. After pushing this commit, the RTD action succeeded. * build(docs): Sphinx stale cross refs false success I figured out why I kept getting warnings for broken Sphinx cross-refs *after* the changes that caused them have already been merged, changes I know I ran `$ make docs` for before pushing. The issue is that by default Sphinx only builds changed files for faster iterations while editing, but it only catches broken cross-refs when it builds files. So if changing, for example, a section name in one page that is referenced from another page that you do *not* change, then the warning will be missed until something changes that other page, such as a pull or rebase. I considered adding a separate `./Makefile` target for incremental builds in the inner loop of making changes. But I opted to just remove the `--write-all` CLI option locally while editing in the inner loop, because the uncommitted change will remind me to revert it and run a full rebuild before pushing.
107 lines
3.4 KiB
ReStructuredText
107 lines
3.4 KiB
ReStructuredText
Usage
|
|
=====
|
|
|
|
.. code-block::
|
|
|
|
ytdl-sub [GENERAL OPTIONS] {sub,dl,view} [COMMAND OPTIONS]
|
|
|
|
For Windows users, it would be ``ytdl-sub.exe``
|
|
|
|
|
|
General Options
|
|
---------------
|
|
|
|
CLI options common to all sub-commands. Must be specified before the sub-command, for
|
|
example ``$ ytdl-sub --dry-run sub ...``:
|
|
|
|
.. code-block:: text
|
|
|
|
-h, --help show this help message and exit
|
|
-v, --version show program's version number and exit
|
|
-c CONFIGPATH, --config CONFIGPATH
|
|
path to the config yaml, uses config.yaml if not provided
|
|
-d, --dry-run preview what a download would output, does not perform any video downloads or writes to output directories
|
|
-l quiet|info|verbose|debug, --log-level quiet|info|verbose|debug
|
|
level of logs to print to console, defaults to verbose
|
|
-t TRANSACTIONPATH, --transaction-log TRANSACTIONPATH
|
|
path to store the transaction log output of all files added, modified, deleted
|
|
-st, --suppress-transaction-log
|
|
do not output transaction logs to console or file
|
|
-nc, --suppress-colors
|
|
do not use colors in ytdl-sub output
|
|
-m MATCH [MATCH ...], --match MATCH [MATCH ...]
|
|
match subscription names to one or more substrings, and only run those subscriptions
|
|
|
|
|
|
Subscriptions Options
|
|
---------------------
|
|
|
|
Download all subscriptions specified in each :doc:`subscriptions file
|
|
<./guides/getting_started/subscriptions>`.
|
|
|
|
.. code-block::
|
|
|
|
ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
|
|
|
|
``SUBPATH`` is one or more paths to subscription files and defaults to
|
|
``./subscriptions.yaml`` if none are given. It will use the config specified by
|
|
``--config``, or ``./config.yaml``, if not provided.
|
|
|
|
.. code-block:: text
|
|
:caption: Additional Options
|
|
|
|
-u, --update-with-info-json
|
|
update all subscriptions with the current config using info.json files
|
|
-o DL_OVERRIDE, --dl-override DL_OVERRIDE
|
|
override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
|
|
|
|
|
|
Download Options
|
|
----------------
|
|
|
|
Download a single subscription in the form of CLI arguments instead of from :doc:`a
|
|
subscriptions file <./guides/getting_started/subscriptions>`:
|
|
|
|
.. code-block::
|
|
|
|
ytdl-sub [GENERAL OPTIONS] dl [SUBSCRIPTION ARGUMENTS]
|
|
|
|
``SUBSCRIPTION ARGUMENTS`` are the same as YAML arguments, but use periods (``.``)
|
|
instead of indents. 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_reference/config_yaml.html#ytdl_sub.config.config_validator.ConfigOptions.dl_aliases>`_.
|
|
|
|
|
|
View Options
|
|
------------
|
|
|
|
Preview the source variables for a given URL. Helpful to create new subscriptions:
|
|
|
|
.. code-block::
|
|
|
|
ytdl-sub view [-sc] [URL]
|
|
|
|
.. code-block:: text
|
|
:caption: Additional Options
|
|
|
|
-sc, --split-chapters
|
|
View source variables after splitting by chapters
|