docs: improve config-file + plugin sideloading

2023-07-15 15:38:38 +02:00 · 2023-07-15 15:38:38 +02:00 · 07d627fbef
parent 0d4e81debd
commit 07d627fbef
2 changed files with 124 additions and 58 deletions
--- 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 <xdg-base-dir-arch-wiki_>`_).
+   The ``XDG_CONFIG_HOME`` environment variable is part of the `XDG base directory specification`_ (`Arch Linux Wiki <xdg-base-dir-arch-wiki_>`_).

   The ``${VARIABLENAME:-DEFAULTVALUE}`` syntax is explained `here <Parameter expansion_>`_.

 .. _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 ``.<plugin name>`` attached to the end.
-
-Examples
-^^^^^^^^
+Streamlink expects these configs to be named like the main config but with ``.<plugin name>`` 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 <plugins:Plugins>`, or
 check the :option:`--plugins` option to see the name of each built-in plugin.
--- 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.