diff --git a/docs/source/config_reference/config_yaml.rst b/docs/source/config_reference/config_yaml.rst index 6c065bc9..6955c386 100644 --- a/docs/source/config_reference/config_yaml.rst +++ b/docs/source/config_reference/config_yaml.rst @@ -33,8 +33,17 @@ subscriptions. persist_logs ~~~~~~~~~~~~ -Within ``configuration``, define whether logs from subscription downloads should be -persisted. +Without this key, ``ytdl-sub`` only prints output to it's ``stdout`` and ``stderr``. If +your configuration includes the ``persist_logs:`` key, then ``ytdl-sub`` also writes log +files to disk. + +.. warning:: + + The log files grow rapidly if ``keep_successful_logs:`` is ``true``, the default, and + may fill up disk space. Set ``keep_successful_logs: false`` or prune the log files + regularly. + +For example: .. code-block:: yaml @@ -42,9 +51,6 @@ persisted. persist_logs: logs_directory: "/path/to/log/directory" -Log files are stored as -``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. - .. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator() :members: :member-order: bysource diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 68f45651..8f828858 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -11,14 +11,15 @@ For Windows users, it would be ``ytdl-sub.exe`` General Options --------------- -General options must be specified before the command (i.e. ``sub``). +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 + 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 info @@ -30,18 +31,19 @@ General options must be specified before the command (i.e. ``sub``). match subscription names to one or more substrings, and only run those subscriptions -Sub Options ------------ +Subscriptions Options +--------------------- -Download all subscriptions specified in each ``SUBPATH``. +Download all subscriptions specified in each :doc:`subscriptions file +<./guides/getting_started/first_sub>`. .. 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. +``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 @@ -55,15 +57,15 @@ not provided. Download Options ---------------- -Download a single subscription in the form of CLI arguments. +Download a single subscription in the form of CLI arguments instead of from :doc:`a +subscriptions file <./guides/getting_started/first_sub>`: .. 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: +``SUBSCRIPTION ARGUMENTS`` are the same as YAML arguments, but use periods (``.``) +instead of indents. For example, you can represent this subscription: .. code-block:: yaml @@ -90,6 +92,8 @@ See how to shorten commands using `download aliases View Options ------------ +Preview the source variables for a given URL. Helpful to create new subscriptions: + .. code-block:: ytdl-sub view [-sc] [URL] @@ -99,5 +103,3 @@ View Options -sc, --split-chapters View source variables after splitting by chapters - -Preview the source variables for a given URL. Helps when creating new configs. diff --git a/examples/advanced/tv_show_config.yaml b/examples/advanced/tv_show_config.yaml index 9cfa4ca7..d2019b9a 100644 --- a/examples/advanced/tv_show_config.yaml +++ b/examples/advanced/tv_show_config.yaml @@ -1,9 +1,9 @@ ############################################################################### -# Top-level configurations to apply umask and persist error logs +# Top-level configurations to apply umask and write log files configuration: umask: "002" persist_logs: - logs_directory: './logs' + logs_directory: '/config/logs' keep_successful_logs: False presets: @@ -98,4 +98,4 @@ presets: overrides: only_recent_date_range: "2months" - only_recent_max_files: 30 \ No newline at end of file + only_recent_max_files: 30 diff --git a/src/ytdl_sub/config/config_validator.py b/src/ytdl_sub/config/config_validator.py index 55a91f55..b5d234a9 100644 --- a/src/ytdl_sub/config/config_validator.py +++ b/src/ytdl_sub/config/config_validator.py @@ -67,7 +67,8 @@ class PersistLogsValidator(StrictDictValidator): @property def logs_directory(self) -> str: """ - Required. The directory to store the logs in. + Write log files to this directory with names like + ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required) """ return self._logs_directory.value @@ -92,7 +93,10 @@ class PersistLogsValidator(StrictDictValidator): @property def keep_successful_logs(self) -> bool: """ - Optional. Whether to store logs when downloading is successful. Defaults to True. + If the ``persist_logs:`` key is in the configuration, then ``ytdl-sub`` *always* + writes log files for the subscription both for successful downloads and when it + encounters an error while downloading. When this key is ``False``, only write + log files for errors. (default ``True``) """ return self._keep_successful_logs.value @@ -147,7 +151,7 @@ class ConfigOptions(StrictDictValidator): def working_directory(self) -> str: """ The directory to temporarily store downloaded files before moving them into their final - directory. Defaults to .ytdl-sub-working-directory + directory. (default ``./.ytdl-sub-working-directory``) """ # Expands tildas to actual paths, use native os sep return os.path.expanduser(self._working_directory.value.replace(posixpath.sep, os.sep)) @@ -155,7 +159,7 @@ class ConfigOptions(StrictDictValidator): @property def umask(self) -> Optional[str]: """ - Umask (octal format) to apply to every created file. Defaults to "022". + Umask in octal format to apply to every created file. (default ``022``) """ return self._umask.value @@ -214,24 +218,25 @@ class ConfigOptions(StrictDictValidator): def lock_directory(self) -> str: """ The directory to temporarily store file locks, which prevents multiple instances - of ``ytdl-sub`` from running. Note that file locks do not work on network-mounted - directories. Ensure that this directory resides on the host machine. Defaults to ``/tmp``. + of ``ytdl-sub`` from running. Note that file locks do not work on + network-mounted directories. Ensure that this directory resides on the host + machine. (default ``/tmp``) """ return self._lock_directory.value @property def ffmpeg_path(self) -> str: """ - Path to ffmpeg executable. Defaults to ``/usr/bin/ffmpeg`` for Linux, and - ``ffmpeg.exe`` for Windows (in the same directory as ytdl-sub). + Path to ffmpeg executable. (default ``/usr/bin/ffmpeg`` for Linux, + ``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows) """ return self._ffmpeg_path.value @property def ffprobe_path(self) -> str: """ - Path to ffprobe executable. Defaults to ``/usr/bin/ffprobe`` for Linux, and - ``ffprobe.exe`` for Windows (in the same directory as ytdl-sub). + Path to ffprobe executable. (default ``/usr/bin/ffprobe`` for Linux, + ``./ffprobe.exe`` in the same directory as ytdl-sub for Windows) """ return self._ffprobe_path.value