abd75f8005
* docs(logs): Mimick argparse option default format I find it more readable to use punctuation to separate technical information, such as required vs optional or default values, from narrative description. Follow argparse's lead, and put such information in parens following the narrative description. * docs(usage): Consistent structure, clarifications * docs(config): Clarify persist_logs behavior/opts Clarify the `persist_logs:` options per [Discord discussion](https://discord.com/channels/994270357957648404/1409161361853780060/1409602529460879431).
123 lines
3.3 KiB
ReStructuredText
123 lines
3.3 KiB
ReStructuredText
==================
|
|
Configuration File
|
|
==================
|
|
|
|
ytdl-sub is configured using a ``config.yaml`` file.
|
|
|
|
The ``config.yaml`` is made up of two sections:
|
|
|
|
.. code-block:: yaml
|
|
|
|
configuration:
|
|
presets:
|
|
|
|
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 and
|
|
subscriptions.
|
|
|
|
.. autoclass:: ytdl_sub.config.config_validator.ConfigOptions()
|
|
:members:
|
|
:member-order: bysource
|
|
:exclude-members: subscription_value, persist_logs, experimental
|
|
|
|
persist_logs
|
|
~~~~~~~~~~~~
|
|
|
|
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
|
|
|
|
configuration:
|
|
persist_logs:
|
|
logs_directory: "/path/to/log/directory"
|
|
|
|
.. autoclass:: ytdl_sub.config.config_validator.PersistLogsValidator()
|
|
:members:
|
|
:member-order: bysource
|
|
|
|
|
|
presets
|
|
-------
|
|
|
|
Each key under ``presets:`` defines a `formula` for how to format downloaded media and
|
|
metadata. The key is the name of the preset and the value is a mapping that defines the
|
|
preset.
|
|
|
|
.. note::
|
|
|
|
The ``presets:`` key at the top of the configuration file contains multiple
|
|
user-defined presets, but *each preset* itself may include a ``preset:`` key that
|
|
defines *that preset's* base presets. For example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
presets:
|
|
Foo Preset:
|
|
preset:
|
|
- "Jellyfin TV Show by Date"
|
|
- "Only Recent"
|
|
|
|
preset
|
|
~~~~~~
|
|
|
|
Presets support inheritance by defining one or more parent presets:
|
|
|
|
.. code-block:: yaml
|
|
|
|
presets:
|
|
custom_preset:
|
|
...
|
|
parent_preset:
|
|
...
|
|
child_preset:
|
|
preset:
|
|
- "parent_preset"
|
|
|
|
In the example above, ``child_preset`` inherits all fields defined in ``parent_preset``.
|
|
Use parent presets where possible to reduce duplicate yaml definitions.
|
|
|
|
Presets also support inheritance from multiple presets:
|
|
|
|
.. code-block:: yaml
|
|
|
|
child_preset:
|
|
preset:
|
|
- "custom_preset"
|
|
- "parent_preset"
|
|
|
|
In this example, ``child_preset`` will inherit all fields from ``custom_preset`` and
|
|
``parent_preset`` in that order. The bottom-most preset has the highest priority. More
|
|
specifically, presets are merged using `mergedeep`_ via `a TYPESAFE_ADDITIVE merge`_,
|
|
which means:
|
|
|
|
- if two conflicting keys arent lists or mappings, overwrite the higher priority one
|
|
- otherwise, combine then re-evaluate
|
|
|
|
If you are only inheriting from one preset, using a single string instead of a list is
|
|
valid, for example ``preset: "parent_preset"``, but we recommend always using a list for
|
|
consistent readability between presets.
|
|
|
|
.. _`mergedeep`:
|
|
https://mergedeep.readthedocs.io/en/latest/
|
|
.. _`a TYPESAFE_ADDITIVE merge`:
|
|
https://mergedeep.readthedocs.io/en/latest/index.html#merge-strategies
|