Merge pull request #1901 from sopel-irc/document-env-vars

doc: cover environment variable support

Author: dgw

docs/source/cli.rst

@@ -16,6 +16,10 @@ to, and channels to join. By default, it creates the file
 Once this is done, the ``start`` subcommand runs the bot, using this
 configuration file unless one is provided using the ``-c``/``--config`` option.
 
+Certain command-line options can be passed via environment variables. Also see
+the :ref:`section on environment variables <Supported environment variables>`
+for more possibilities.
+
 .. contents::
     :local:
     :depth: 1
@@ -67,3 +71,80 @@ The ``sopel-plugins`` command
 
 .. autoprogram:: sopel.cli.plugins:build_parser()
     :prog: sopel-plugins
+
+
+Supported environment variables
+===============================
+
+
+``SOPEL_CONFIG``
+----------------
+
+This environment variable replaces the built-in default config name (which is,
+confusingly, also "default") if set. It's interpreted in the same way as the
+``-c``/``--config`` option accepted by most CLI commands described above.
+
+.. versionadded:: 7.0
+
+
+``SOPEL_CONFIG_DIR``
+--------------------
+
+This environment variable replaces the default directory in which Sopel
+searches for config files. It's interpreted in the same way as the
+``--config-dir`` option accepted by most CLI commands described above.
+
+.. versionadded:: 7.1
+
+
+Overriding individual settings
+------------------------------
+
+Whenever a setting is accessed, Sopel looks for a matching environment
+variable. If found, the environment variable's value (even if it's empty)
+overrides the value from Sopel's config file.
+
+The variable name Sopel looks for is structured as follows:
+
+  * ``SOPEL_`` prefix (to prevent collisions with other programs)
+  * The section name in UPPERCASE, e.g. ``CORE`` or ``PLUGIN_NAME``
+  * ``_`` as separator
+  * The setting name in UPPERCASE, e.g. ``NICK`` or ``API_KEY``
+
+For example, take this stripped-down config file:
+
+.. code-block:: ini
+
+    [core]
+    nick = ConfigFileNick
+    host = chat.freenode.net
+
+    [plugin_name]
+    api_key = abad1dea
+
+Sopel would take the nickname ``ConfigFileNick`` when connecting to IRC at
+``chat.freenode.net``, and the ``plugin_name`` plugin would use the API key
+``abad1dea`` when communicating with its remote service.
+
+However, by setting the environment variables:
+
+.. code-block:: shell
+
+    SOPEL_CORE_NICK=EnvVarNick
+    SOPEL_PLUGIN_NAME_API_KEY=1337c0ffee9001
+
+Sopel would take the nickname ``EnvVarNick`` when connecting to IRC (still at
+``chat.freenode.net``; that value isn't overridden or lost), and the
+``plugin_name`` plugin would use the API key ``1337c0ffee9001``, instead.
+
+.. versionadded:: 7.0
+
+.. note::
+
+   Any ``_`` character in the section or setting name also appears in the
+   environment variable name. It's therefore *theoretically* possible for two
+   plugins to have section and setting name pairs that both resolve to the same
+   environment variable name, but in practice this is highly unlikely.
+
+   However, should such a collision occur, please notify the main Sopel project
+   *and* both plugin authors via any relevant communication channel(s).

docs/source/plugin.rst

@@ -13,6 +13,26 @@ A Sopel plugin consists of a Python module containing one or more
 ``callable``\s. It may optionally also contain ``configure``, ``setup``, and
 ``shutdown`` hooks.
 
+Sopel plugins conventionally have all-lowercase names, usually one word.
+However, sometimes multiple words are needed for clarity or disambiguation;
+``snake_case`` is normally used for these.
+
+.. note::
+
+    How Sopel determines a plugin's name depends on what kind of plugin it is:
+
+    Single file
+      The file's basename (e.g. ``plugin`` in ``plugin.py``)
+
+    Folder
+      The folder name (e.g. ``plugin`` in ``~/.sopel/plugins/plugin/__init__.py``)
+
+    Namespace package
+      The submodule name (e.g. ``plugin`` in ``sopel_modules.plugin``)
+
+    Entry point
+      The entry point name (e.g. ``plugin`` in ``plugin = my_plugin.module.path``)
+
 .. py:function:: callable(bot, trigger)
 
     :param bot: the bot's instance

sopel/config/__init__.py

@@ -194,6 +194,20 @@ def add_section(self, name):
             :meth:`define_section` and a child class of
             :class:`~.types.StaticSection`.
 
+        .. important::
+
+            The section's ``name`` SHOULD follow *snake_case* naming rules:
+
+              * use only lowercase letters, digits, and underscore (``_``)
+              * SHOULD NOT start with a digit
+
+            Deviations from *snake_case* can break the following operations:
+
+              * :ref:`accessing the section <sopel.config>` from Python code using
+                the :class:`~.Config` object's attributes
+              * :ref:`overriding the section's values <Overriding individual
+                settings>` using environment variables
+
         """
         try:
             return self.parser.add_section(name)
@@ -216,6 +230,21 @@ def define_section(self, name, cls_, validate=True):
         raised if they are invalid. This is desirable in a plugin's
         :func:`setup` function, for example, but might not be in the
         :func:`configure` function.
+
+        .. important::
+
+            The section's ``name`` SHOULD follow *snake_case* naming rules:
+
+              * use only lowercase letters, digits, and underscore (``_``)
+              * SHOULD NOT start with a digit
+
+            Deviations from *snake_case* can break the following operations:
+
+              * :ref:`accessing the section <sopel.config>` from Python code using
+                the :class:`~.Config` object's attributes
+              * :ref:`overriding the section's values <Overriding individual
+                settings>` using environment variables
+
         """
         if not issubclass(cls_, types.StaticSection):
             raise ValueError("Class must be a subclass of StaticSection.")

sopel/config/types.py

@@ -47,6 +47,18 @@ class StaticSection(object):
 
     This class is intended to be subclassed and customized with added
     attributes containing :class:`BaseValidated`-based objects.
+
+    .. note::
+
+        By convention, subclasses of ``StaticSection`` are named with the
+        plugin's name in CamelCase, plus the suffix ``Section``. For example, a
+        plugin named ``editor`` might name its subclass ``EditorSection``; a
+        ``do_stuff`` plugin might name its subclass ``DoStuffSection`` (its
+        name converted from ``snake_case`` to ``CamelCase``).
+
+        However, this is *only* a convention. Any class name that is legal in
+        Python will work just fine.
+
     """
     def __init__(self, config, section_name, validate=True):
         if not config.parser.has_section(section_name):
@@ -120,6 +132,21 @@ class BaseValidated(object):
     the value *must* be configured by the user (i.e. there is no suitable
     default value). Trying to read an empty ``NO_DEFAULT`` value will raise
     :class:`AttributeError`.
+
+    .. important::
+
+        Setting names SHOULD follow *snake_case* naming rules:
+
+          * use only lowercase letters, digits, and underscore (``_``)
+          * SHOULD NOT start with a digit
+
+        Deviations from *snake_case* can break the following operations:
+
+          * :ref:`accessing the setting <sopel.config>` from Python code using
+            the :class:`~.Config` object's attributes
+          * :ref:`overriding the setting's value <Overriding individual
+            settings>` using environment variables
+
     """
     def __init__(self, name, default=None, is_secret=False):
         self.name = name