diff --git a/docs/source/conf.py b/docs/source/conf.py index ef717d14..c226b589 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -68,4 +68,3 @@ extlinks = { "lsio-gh": ("https://github.com/linuxserver/%s", "%s image"), "ytdl-sub-gh": ("https://github.com/jmbannon/ytdl-sub/%s", "src %s"), } - diff --git a/docs/source/config_reference/config_yaml.rst b/docs/source/config_reference/config_yaml.rst index c3fab0c7..ccfa901b 100644 --- a/docs/source/config_reference/config_yaml.rst +++ b/docs/source/config_reference/config_yaml.rst @@ -20,14 +20,37 @@ The ``config.yaml`` is made up of two sections: Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``. If you prefer to use a Windows backslash, note that it must have -``C:\double\bashslash\paths`` in order to escape the backslash character. This is due to -it being a YAML escape character. +``C:\\double\\bashslash\\paths`` in order to escape the backslash character. This is due +to it being a YAML escape character. + +.. code-block:: yaml + + configuration: + dl_aliases: + mv: "--preset music_video" + u: "--download.url" + + experimental: + enable_update_with_info_json: True + + ffmpeg_path: "/usr/bin/ffmpeg" + ffprobe_path: "/usr/bin/ffprobe" + + file_name_max_bytes: 255 + lock_directory: "/tmp" + + persist_logs: + keep_successful_logs: True + logs_directory: "/var/log/ytdl-sub-logs" + + umask: "022" + working_directory: ".ytdl-sub-working-directory" dl_aliases ---------- .. _dl_aliases: -Alias definitions to shorten ``ytdl-sub dl`` arguments. For example, +Alias definitions to shorten :ref:`dl arguments `. For example, .. code-block:: yaml @@ -50,13 +73,7 @@ to experimental ------------ -Experimental flags reside under the ``experimental`` key: - - .. code-block:: yaml - - configuration: - experimental: - enable_update_with_info_json: True +Experimental flags reside under the ``experimental`` key. ``enable_update_with_info_json`` @@ -66,13 +83,13 @@ destroy files. Ensure you have a full backup before usage. You have been warned! ffmpeg_path ----------- -Path to ffmpeg executable. (default ``/usr/bin/ffmpeg`` for Linux, -``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows) +Path to ffmpeg executable. Defaults to ``/usr/bin/ffmpeg`` for Linux, +``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows. ffprobe_path ------------ -Path to ffprobe executable. (default ``/usr/bin/ffprobe`` for Linux, -``./ffprobe.exe`` in the same directory as ytdl-sub for Windows) +Path to ffprobe executable. Defaults to ``/usr/bin/ffprobe`` for Linux, +``./ffprobe.exe`` in the same directory as ytdl-sub for Windows. file_name_max_bytes ------------------- @@ -83,39 +100,35 @@ lock_directory 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. (default ``/tmp``) +machine. Defaults to ``/tmp``. persist_logs ------------ -TODO(jessebannon) fill out +By default, no logs are persisted. Specifying this key will enable persisted logs. The following +options are available. ``keep_successful_logs`` -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``) +Defaults to ``True``. When this key is ``False``, only write log files for failed +subscriptions. ``logs_directory`` -Write log files to this directory with names like -``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required) +Required field. Write log files to this directory with names like +``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. umask ----- -Umask in octal format to apply to every created file. (default ``022``) +Umask in octal format to apply to every created file. Defaults to ``022``. working_directory ----------------- The directory to temporarily store downloaded files before moving them into their final -directory. (default ``./.ytdl-sub-working-directory``) +directory. Defaults to ``.ytdl-sub-working-directory``, created in the same directory +that ytdl-sub is invoked from. Presets ======= -Hmmmm - -``name`` - -Returns -------- -Name of the preset +Custom presets are defined in this section. Refer to the +:ref:`Getting Started Guide` +on how to configure. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 0db65064..cb5b827e 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -87,8 +87,7 @@ Using the command: --overrides.tv_show_name "Rick A" \ --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" -See how to shorten commands using `download aliases -`_. +See how to shorten commands using :ref:`download aliases `. View Options diff --git a/src/ytdl_sub/config/config_validator.py b/src/ytdl_sub/config/config_validator.py index abcb0e24..0dc2c1e0 100644 --- a/src/ytdl_sub/config/config_validator.py +++ b/src/ytdl_sub/config/config_validator.py @@ -25,13 +25,7 @@ from ytdl_sub.validators.validators import StringValidator class ExperimentalValidator(StrictDictValidator): """ - Experimental flags reside under the ``experimental`` key: - - .. code-block:: yaml - - configuration: - experimental: - enable_update_with_info_json: True + Experimental flags reside under the ``experimental`` key. """ _optional_keys = {"enable_update_with_info_json"} @@ -56,7 +50,8 @@ class ExperimentalValidator(StrictDictValidator): class PersistLogsValidator(StrictDictValidator): """ - TODO(jessebannon) fill out + By default, no logs are persisted. Specifying this key will enable persisted logs. The following + options are available. """ _required_keys = {"logs_directory"} @@ -83,8 +78,8 @@ class PersistLogsValidator(StrictDictValidator): @property def logs_directory(self) -> str: """ - Write log files to this directory with names like - ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. (required) + Required field. Write log files to this directory with names like + ``YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log``. """ return self._logs_directory.value @@ -109,10 +104,8 @@ class PersistLogsValidator(StrictDictValidator): @property def keep_successful_logs(self) -> bool: """ - 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``) + Defaults to ``True``. When this key is ``False``, only write log files for failed + subscriptions. """ return self._keep_successful_logs.value @@ -131,8 +124,32 @@ class ConfigOptions(StrictDictValidator): Note for Windows users, paths can be represented with ``C:/forward/slashes/like/linux``. If you prefer to use a Windows backslash, note that it must have - ``C:\\double\\bashslash\\paths`` in order to escape the backslash character. This is due to - it being a YAML escape character. + ``C:\\\\double\\\\bashslash\\\\paths`` in order to escape the backslash character. This is due + to it being a YAML escape character. + + .. code-block:: yaml + + configuration: + dl_aliases: + mv: "--preset music_video" + u: "--download.url" + + experimental: + enable_update_with_info_json: True + + ffmpeg_path: "/usr/bin/ffmpeg" + ffprobe_path: "/usr/bin/ffprobe" + + file_name_max_bytes: 255 + lock_directory: "/tmp" + + persist_logs: + keep_successful_logs: True + logs_directory: "/var/log/ytdl-sub-logs" + + umask: "022" + working_directory: ".ytdl-sub-working-directory" + """ _optional_keys = { @@ -190,7 +207,8 @@ class ConfigOptions(StrictDictValidator): def working_directory(self) -> str: """ The directory to temporarily store downloaded files before moving them into their final - directory. (default ``./.ytdl-sub-working-directory``) + directory. Defaults to ``.ytdl-sub-working-directory``, created in the same directory + that ytdl-sub is invoked from. """ # Expands tildas to actual paths, use native os sep return os.path.expanduser(self._working_directory.value.replace(posixpath.sep, os.sep)) @@ -198,7 +216,7 @@ class ConfigOptions(StrictDictValidator): @property def umask(self) -> Optional[str]: """ - Umask in octal format to apply to every created file. (default ``022``) + Umask in octal format to apply to every created file. Defaults to ``022``. """ return self._umask.value @@ -207,7 +225,7 @@ class ConfigOptions(StrictDictValidator): """ .. _dl_aliases: - Alias definitions to shorten ``ytdl-sub dl`` arguments. For example, + Alias definitions to shorten :ref:`dl arguments `. For example, .. code-block:: yaml @@ -259,23 +277,23 @@ class ConfigOptions(StrictDictValidator): 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. (default ``/tmp``) + machine. Defaults to ``/tmp``. """ return self._lock_directory.value @property def ffmpeg_path(self) -> str: """ - Path to ffmpeg executable. (default ``/usr/bin/ffmpeg`` for Linux, - ``./ffmpeg.exe`` in the same directory as ytdl-sub for Windows) + Path to ffmpeg executable. Defaults to ``/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. (default ``/usr/bin/ffprobe`` for Linux, - ``./ffprobe.exe`` in the same directory as ytdl-sub for Windows) + Path to ffprobe executable. Defaults to ``/usr/bin/ffprobe`` for Linux, + ``./ffprobe.exe`` in the same directory as ytdl-sub for Windows. """ return self._ffprobe_path.value diff --git a/src/ytdl_sub/config/preset.py b/src/ytdl_sub/config/preset.py index 5c3f2ea6..2c8ad348 100644 --- a/src/ytdl_sub/config/preset.py +++ b/src/ytdl_sub/config/preset.py @@ -56,7 +56,9 @@ class _PresetShell(StrictDictValidator): class Preset(_PresetShell): """ - Hmmmm + Custom presets are defined in this section. Refer to the + :ref:`Getting Started Guide` + on how to configure. """ @classmethod diff --git a/tools/docgen/configuration.py b/tools/docgen/configuration.py index 64eb9f89..958c09a1 100644 --- a/tools/docgen/configuration.py +++ b/tools/docgen/configuration.py @@ -28,7 +28,7 @@ class ConfigurationDocGen(DocGen): name="Presets", options=Preset, offset=0, - skip_properties=False, + skip_properties=True, recurse_property_options=False, property_sections=False, )