From 07d627fbeff67d143b8d5fbce4b8caf5bdc05944 Mon Sep 17 00:00:00 2001 From: bastimeyer Date: Sat, 15 Jul 2023 15:38:38 +0200 Subject: [PATCH] docs: improve config-file + plugin sideloading --- docs/cli/config.rst | 127 +++++++++++++++++++++----------- docs/cli/plugin-sideloading.rst | 55 ++++++++++---- 2 files changed, 124 insertions(+), 58 deletions(-) diff --git a/docs/cli/config.rst b/docs/cli/config.rst index 063c5b86..f336a208 100644 --- a/docs/cli/config.rst +++ b/docs/cli/config.rst @@ -12,29 +12,54 @@ your platform: .. rst-class:: table-custom-layout table-custom-layout-platform-locations -================= ==================================================== -Platform Location -================= ==================================================== -Linux, BSD - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config`` +.. list-table:: + :header-rows: 1 + :width: 100% - Deprecated: + * - Platform + - Location + * - Linux, BSD + - :bdg-primary:`Path` - - ``${HOME}/.streamlinkrc`` -macOS - ``${HOME}/Library/Application Support/streamlink/config`` + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config`` - Deprecated: + :bdg-info-line:`Example` - - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config`` - - ``${HOME}/.streamlinkrc`` -Windows - ``%APPDATA%\streamlink\config`` + - ``/home/USERNAME/.config/streamlink/config`` - Deprecated: + :bdg-danger-line:`Deprecated` - - ``%APPDATA%\streamlink\streamlinkrc`` -================= ==================================================== + - ``${HOME}/.streamlinkrc`` + * - macOS + - :bdg-primary:`Path` + + - ``${HOME}/Library/Application Support/streamlink/config`` + + :bdg-info-line:`Example` + + - ``/Users/USERNAME/Library/Application Support/streamlink/config`` + + :bdg-danger-line:`Deprecated` + + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config`` + - ``${HOME}/.streamlinkrc`` + * - Windows + - :bdg-primary:`Path` + + - ``%APPDATA%\streamlink\config`` + + :bdg-info-line:`Example` + + - ``C:\Users\USERNAME\AppData\Roaming\streamlink\config`` + + :bdg-danger-line:`Deprecated` + + - ``%APPDATA%\streamlink\streamlinkrc`` You can also specify the location yourself using the :option:`--config` option. +Loading config files can be suppressed using the :option:`--no-config` option. + .. warning:: Streamlink's Windows installers automatically create a config file if it doesn't exist yet, but on any @@ -42,13 +67,13 @@ You can also specify the location yourself using the :option:`--config` option. .. note:: - The ``XDG_CONFIG_HOME`` environment variable is part of the `XDG base directory specification`_ (`Arch Wiki `_). + The ``XDG_CONFIG_HOME`` environment variable is part of the `XDG base directory specification`_ (`Arch Linux Wiki `_). The ``${VARIABLENAME:-DEFAULTVALUE}`` syntax is explained `here `_. .. _XDG base directory specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html .. _xdg-base-dir-arch-wiki: https://wiki.archlinux.org/title/XDG_Base_Directory -.. _Parameter expansion: https://wiki.bash-hackers.org/syntax/pe +.. _Parameter expansion: https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion Syntax @@ -74,51 +99,65 @@ Example .. code-block:: bash # Player options - player=mpv --cache 2048 + player=mpv + player-args=--cache 2048 player-no-close -.. note:: - - Full player paths are supported via configuration file options such as - ``player=C:\mpv-x86_64\mpv`` - Plugin specific configuration file ---------------------------------- -You may want to use specific options for some plugins only. This -can be accomplished by placing those settings inside a plugin specific -config file. Options inside these config files will override the main +You may want to use specific options for some plugins only. This can be accomplished by setting these options +in plugin-specific config files. Options defined in plugin-specific config files override options of the main config file when a URL matching the plugin is used. -Streamlink expects this config to be named like the main config but -with ``.`` attached to the end. - -Examples -^^^^^^^^ +Streamlink expects these configs to be named like the main config but with ``.`` attached to the end. .. rst-class:: table-custom-layout table-custom-layout-platform-locations -================= ==================================================== -Platform Location -================= ==================================================== -Linux, BSD - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config.pluginname`` +.. list-table:: + :header-rows: 1 + :width: 100% - Deprecated: + * - Platform + - Location + * - Linux, BSD + - :bdg-primary:`Path` - - ``${HOME}/.streamlinkrc.pluginname`` -macOS - ``${HOME}/Library/Application Support/streamlink/config.pluginname`` + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config.pluginname`` - Deprecated: + :bdg-info-line:`Example` - - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config.pluginname`` - - ``${HOME}/.streamlinkrc.pluginname`` -Windows - ``%APPDATA%\streamlink\config.pluginname`` + - ``/home/USERNAME/.config/streamlink/config.twitch`` - Deprecated: + :bdg-danger-line:`Deprecated` - - ``%APPDATA%\streamlink\streamlinkrc.pluginname`` -================= ==================================================== + - ``${HOME}/.streamlinkrc.pluginname`` + * - macOS + - :bdg-primary:`Path` + + - ``${HOME}/Library/Application Support/streamlink/config.pluginname`` + + :bdg-info-line:`Example` + + - ``/Users/USERNAME/Library/Application Support/streamlink/config.twitch`` + + :bdg-danger-line:`Deprecated` + + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/config.pluginname`` + - ``${HOME}/.streamlinkrc.pluginname`` + * - Windows + - :bdg-primary:`Path` + + - ``%APPDATA%\streamlink\config.pluginname`` + + :bdg-info-line:`Example` + + - ``C:\Users\USERNAME\AppData\Roaming\streamlink\config.twitch`` + + :bdg-danger-line:`Deprecated` + + - ``%APPDATA%\streamlink\streamlinkrc.pluginname`` Have a look at the :ref:`list of plugins `, or check the :option:`--plugins` option to see the name of each built-in plugin. diff --git a/docs/cli/plugin-sideloading.rst b/docs/cli/plugin-sideloading.rst index cce0fab9..7e25b30c 100644 --- a/docs/cli/plugin-sideloading.rst +++ b/docs/cli/plugin-sideloading.rst @@ -5,21 +5,44 @@ Streamlink will attempt to load standalone plugins from these directories: .. rst-class:: table-custom-layout table-custom-layout-platform-locations -================= ==================================================== -Platform Location -================= ==================================================== -Linux, BSD - ``${XDG_DATA_HOME:-${HOME}/.local/share}/streamlink/plugins`` +.. list-table:: + :header-rows: 1 + :width: 100% - Deprecated: + * - Platform + - Location + * - Linux, BSD + - :bdg-primary:`Path` - - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/plugins`` -macOS - ``${HOME}/Library/Application Support/streamlink/plugins`` + - ``${XDG_DATA_HOME:-${HOME}/.local/share}/streamlink/plugins`` - Deprecated: + :bdg-info-line:`Example` - - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/plugins`` -Windows - ``%APPDATA%\streamlink\plugins`` -================= ==================================================== + - ``/home/USERNAME/.local/share/streamlink/plugins`` + + :bdg-danger-line:`Deprecated` + + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/plugins`` + * - macOS + - :bdg-primary:`Path` + + - ``${HOME}/Library/Application Support/streamlink/plugins`` + + :bdg-info-line:`Example` + + - ``/Users/USERNAME/Library/Application Support/streamlink/plugins`` + + :bdg-danger-line:`Deprecated` + + - ``${XDG_CONFIG_HOME:-${HOME}/.config}/streamlink/plugins`` + * - Windows + - :bdg-primary:`Path` + + - ``%APPDATA%\streamlink\plugins`` + + :bdg-info-line:`Example` + + - ``C:\Users\USERNAME\AppData\Roaming\streamlink\plugins`` .. note:: @@ -27,9 +50,13 @@ Windows - ``%APPDATA%\streamlink\plugins`` the added plugin will take precedence. This is useful if you want to upgrade plugins independently of the Streamlink version. + In this case, a log message will be written to log level :option:`debug <--loglevel>`: + + [session][debug] Plugin PLUGINNAME is being overridden by PATH-TO-PLUGIN-FILE + .. warning:: - If one of the sideloaded plugins fails to load, eg. due to a - ``SyntaxError`` being raised by the parser, this exception will - not get caught by Streamlink and the execution will stop, even if + If one of the sideloaded plugins fails to load, e.g. due to a + ``SyntaxError`` being raised by the parser, then this exception won't + get caught by Streamlink and the execution will stop, even if the input stream URL does not match the faulty plugin.