Docs for settings overlay & improved hook docs

docs/plugins/concepts.rst

@@ -10,8 +10,8 @@ parts of the system the plugin will actually plug in to perform its job.
 
 There are three types of ways a plugin might attach itself to the system, through so called
 :ref:`mixin <sec-plugins-mixins>` implementations, by attaching itself to specified
-:ref:`hook <sec-plugins-hooks>` or by offering :ref:`helper <sec-plugins-helpers>` functionality to be
-used by other plugins.
+:ref:`hook <sec-plugins-hooks>`, by offering :ref:`helper <sec-plugins-helpers>` functionality to be
+used by other plugins or by providing :ref:`settings overlays <sec-plugins-controlproperties-plugin_settings_overlay>`.
 
 Plugin mixin implementations will get a bunch of :ref:`properties injected <sec-plugins-mixins-injectedproperties>`
 by OctoPrint plugin system to help them work.
@@ -28,11 +28,12 @@ There are three sources of installed plugins that OctoPrint will check during st
   * any python packages registered for the entry point ``octoprint.plugin``.
 
 Each plugin that OctoPrint finds it will first load, then enable. On enabling a plugin, OctoPrint will
-register its declared :ref:`hook handlers <sec-plugins-hooks>` and :ref:`helpers <sec-plugins-helpers>`,
+register its declared :ref:`hook handlers <sec-plugins-hooks>` and :ref:`helpers <sec-plugins-helpers>`, apply
+any :ref:`settings overlays <sec-plugins-controlproperties-plugin_settings_overlay>`,
 :ref:`inject the required properties <sec-plugins-mixins-injectedproperties>` into its declared
 :ref:`mixin implementation <sec-plugins-mixins>` and register those as well.
 
-On disabling a plugin, its hook handlers, helpers and mixin implementations will be de-registered again.
+On disabling a plugin, its hook handlers, helpers, mixin implementations and settings overlays will be de-registered again.
 
 .. image:: ../images/plugins_lifecycle.png
    :align: center

docs/plugins/controlproperties.rst

@@ -19,36 +19,128 @@ plugin subsystem about themselves. These are simple package attributes defined i
 
 The following properties are recognized:
 
+.. _sec-plugins-controlproperties-plugin_name:
+
 ``__plugin_name__``
   Name of your plugin, optional, overrides the name specified in ``setup.py`` if provided. If neither this property nor
   a name from ``setup.py`` is available to the plugin subsystem, the plugin's identifier (= package name) will be
   used instead.
+
+.. _sec-plugins-controlproperties-plugin_version:
+
 ``__plugin_version__``
   Version of your plugin, optional, overrides the version specified in ``setup.py`` if provided.
+
+.. _sec-plugins-controlproperties-plugin_description:
+
 ``__plugin_description__``
   Description of your plugin, optional, overrides the description specified in ``setup.py`` if provided.
+
+.. _sec-plugins-controlproperties-plugin_author:
+
 ``__plugin_author__``
   Author of your plugin, optional, overrides the author specified in ``setup.py`` if provided.
+
+.. _sec-plugins-controlproperties-plugin_url:
+
 ``__plugin_url__``
   URL of the webpage of your plugin, e.g. the Github repository, optional, overrides the URL specified in ``setup.py`` if
   provided.
+
+.. _sec-plugins-controlproperties-plugin_license:
+
 ``__plugin_license__``
   License of your plugin, optional, overrides the license specified in ``setup.py`` if provided.
+
+.. _sec-plugins-controlproperties-plugin_implementation:
+
 ``__plugin_implementation__``
-  Instance of an implementation of one or more :ref:`plugin mixins <sec-plugins-mixins>`.
+  Instance of an implementation of one or more :ref:`plugin mixins <sec-plugins-mixins>`. E.g.
+
+  .. code-block:: python
+
+     __plugin_implementation__ = MyPlugin()
+
+
+.. _sec-plugins-controlproperties-plugin_hooks:
+
 ``__plugin_hooks__``
-  Handlers for one or more of the various :ref:`plugin hooks <sec-plugins-hooks>`.
+  Handlers for one or more of the various :ref:`plugin hooks <sec-plugins-hooks>`. E.g.
+
+  .. code-block:: python
+
+     def handle_gcode_sent(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs):
+         if gcode in ("M106", "M107"):
+             import logging
+             logging.getLogger(__name__).info("We just sent a fan command to the printer!")
+
+     __plugin_hooks__ = {
+         "octoprint.comm.protocol.gcode.sent": handle_gcode_sent
+     }
+
+
+.. _sec-plugins-controlproperties-plugin_check:
+
 ``__plugin_check__``
   Method called upon discovery of the plugin by the plugin subsystem, should return ``True`` if the
   plugin can be instantiated later on, ``False`` if there are reasons why not, e.g. if dependencies
-  are missing.
+  are missing. An example:
+
+  .. code-block:: python
+
+     def __plugin_check__():
+         # Make sure we only run our plugin if some_dependency is available
+         try:
+             import some_dependency
+         except ImportError:
+             return False
+
+         return True
+
+.. _sec-plugins-controlproperties-plugin_load:
+
 ``__plugin_load__``
   Method called upon loading of the plugin by the plugin subsystem, can be used to instantiate
-  plugin implementations, connecting them to hooks etc.
+  plugin implementations, connecting them to hooks etc. An example:
+
+  .. code-block:: python
+
+     def __plugin_load__():
+         global __plugin_implementation__
+         __plugin_implementation__ = MyPlugin()
+
+         global __plugin_hooks__
+         __plugin_hooks__ = {
+             "octoprint.plugin.softwareupdate.check_config": __plugin_implementation__.get_update_information
+         }
+
+
+.. _sec-plugins-controlproperties-plugin_unload:
+
 ``__plugin_unload__``
   Method called upon unloading of the plugin by the plugin subsystem, can be used to do any final clean ups.
-``__plugin_enable__``
-  Method called upon enabling of the plugin by the plugin subsystem. Also see :func:`~octoprint.plugin.core.Plugin.on_plugin_enabled``.
-``__plugin_disable__``
-  Method called upon disabling of the plugin by the plugin subsystem. Also see :func:`~octoprint.plugin.core.Plugin.on_plugin_disabled``.
 
+.. _sec-plugins-controlproperties-plugin_enable:
+
+``__plugin_enable__``
+  Method called upon enabling of the plugin by the plugin subsystem. Also see :func:`~octoprint.plugin.core.Plugin.on_plugin_enabled`.
+
+.. _sec-plugins-controlproperties-plugin_disable:
+
+``__plugin_disable__``
+  Method called upon disabling of the plugin by the plugin subsystem. Also see :func:`~octoprint.plugin.core.Plugin.on_plugin_disabled`.
+
+.. _sec-plugins-controlproperties-plugin_settings_overlay:
+
+``__plugin_settings_overlay__``
+  An optional ``dict`` providing an overlay over the application's default settings. Plugins can use that to modify the
+  **default** settings of OctoPrint and its plugins that apply when there's no different configuration present in ``config.yaml``. Note that ``config.yaml``
+  has the final say - it is not possible to override what is in there through an overlay. Plugin authors should use this
+  sparingly - it's supposed to be utilized when creating specific customization of the core application that necessitate
+  changes in things like e.g. standard naming, UI ordering or API endpoints. Example:
+
+  .. code-block:: python
+
+     __plugin_settings_overlay__ = dict(api=dict(enabled=False),
+                                        server=dict(host="127.0.0.1",
+                                                    port=5001))

docs/plugins/hooks.rst

@@ -193,7 +193,8 @@ Available plugin hooks
 
 .. note::
 
-   All of the hooks below take at least two parameters, ``*args`` and ``**kwargs``. Please make sure those are present.
+   All of the hooks below take at least two parameters, ``*args`` and ``**kwargs``. Make sure those are
+   **always** present in your hook handler declaration.
    They will act as placeholders if additional parameters are added to the hooks in the future and will allow
    your plugin to stay compatible to OctoPrint without any necessary adjustments from you in these cases.