Merge ~jugmac00/lpci:create-documentation-for-plugin-system into lpci:main

[Jürgen Gmach]

Create documentation for the plugin system

[Colin Watson (cjwatson)]

review: Approve

[Jürgen Gmach (jugmac00)]

Thanks - I moved the `__all__` declarations in between the from future and the regular imports.

Unfortunately, I have not found a flake8 plugin to enforce this behavior.

diff --git a/docs/conf.py b/docs/conf.py
index 7943bc6..4bb3580 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -26,7 +26,7 @@ copyright = "2021, Canonical Ltd"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ["sphinx.ext.autodoc"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
diff --git a/docs/configuration.rst b/docs/configuration.rst
index eb8e5c3..a350f7e 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -57,6 +57,9 @@ Job definitions
     A mapping of environment variable names to values, to be set while
     running the job.
 
+``plugin`` (optional)
+    A plugin which will be used for this job. See :doc:`../plugins`
+
 ``run`` (optional)
     A string (possibly multi-line) containing shell commands to run for this
     job.
diff --git a/docs/plugins.rst b/docs/plugins.rst
index ca26449..f150687 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -19,9 +19,54 @@ Plugin discovery
 ----------------
 
 As currently only builtin plugins are supported,
-you need to define a plugin in ``lpcraft/plugins/<plugin>``.
+you need to define a plugin in ``lpcraft/plugins/<plugin>``
+and import the module in ``lpcraft/plugins/__init__.py``.
 
+Plugin implementation
+---------------------
 
-.. comments
+Please consult the `pluggy <https://pluggy.readthedocs.io/>`_  documentation,
+and have a look at the ``lpcraft/plugins`` directory for inspiration.
 
-    XXX jugmac00 2021-12-17: render all available hooks via plugin
+Name of the hook
+****************
+
+.. automodule:: lpcraft.plugin
+   :members:
+   :exclude-members: hookimpl
+
+Implementation marker
+*********************
+
+.. autodata:: lpcraft.plugin.hookimpl
+   :no-value:
+
+Available hooks
+***************
+
+.. automodule:: lpcraft.plugin.hookspecs
+   :members:
+
+
+Builtin plugins
+---------------
+
+.. automodule:: lpcraft.plugins.plugins
+   :members:
+
+Using a builtin plugin
+----------------------
+
+In order to use a plugin,
+it has to be specified via the ``plugin`` key in the job definition.
+
+.. code-block:: yaml
+
+    pipeline:
+        - test
+
+    jobs:
+        test:
+            series: focal
+            architectures: amd64
+            plugin: tox
diff --git a/lpcraft/plugin/__init__.py b/lpcraft/plugin/__init__.py
index d514ac6..1a01a6c 100644
--- a/lpcraft/plugin/__init__.py
+++ b/lpcraft/plugin/__init__.py
@@ -1,6 +1,12 @@
 # Copyright 2021 Canonical Ltd.  This software is licensed under the
 # GNU General Public License version 3 (see the file LICENSE).
 
+__all__ = ["NAME", "hookimpl"]
+
 import pluggy
 
-hookimpl = pluggy.HookimplMarker("lpcraft")
+NAME = "lpcraft"  #: name of the hook
+
+hookimpl = pluggy.HookimplMarker(
+    NAME
+)  #: decorator to mark lpcraft plugin hooks
diff --git a/lpcraft/plugin/hookspecs.py b/lpcraft/plugin/hookspecs.py
index e1232f4..cef7971 100644
--- a/lpcraft/plugin/hookspecs.py
+++ b/lpcraft/plugin/hookspecs.py
@@ -3,9 +3,18 @@
 
 from __future__ import annotations
 
+__all__ = [
+    "lpcraft_install_packages",
+    "lpcraft_install_snaps",
+    "lpcraft_execute_run",
+    "lpcraft_set_environment",
+]
+
 import pluggy
 
-hookspec = pluggy.HookspecMarker("lpcraft")
+from lpcraft.plugin import NAME
+
+hookspec = pluggy.HookspecMarker(NAME)
 
 
 @hookspec  # type: ignore
diff --git a/lpcraft/plugin/manager.py b/lpcraft/plugin/manager.py
index f2cf7b9..d78f306 100644
--- a/lpcraft/plugin/manager.py
+++ b/lpcraft/plugin/manager.py
@@ -2,13 +2,13 @@ import pluggy
 
 from lpcraft.config import Job
 from lpcraft.errors import ConfigurationError
-from lpcraft.plugin import hookspecs
+from lpcraft.plugin import NAME, hookspecs
 from lpcraft.plugin.lib import InternalPlugins
 from lpcraft.plugins import PLUGINS
 
 
 def get_plugin_manager(job: Job) -> pluggy.PluginManager:
-    pm = pluggy.PluginManager("lpcraft")
+    pm = pluggy.PluginManager(NAME)
     pm.add_hookspecs(hookspecs)
 
     # register internal plugins
diff --git a/lpcraft/plugins/__init__.py b/lpcraft/plugins/__init__.py
index 0c44aa5..205d284 100644
--- a/lpcraft/plugins/__init__.py
+++ b/lpcraft/plugins/__init__.py
@@ -1,6 +1,6 @@
 from typing import Any, Callable, Type, TypeVar
 
-PLUGINS = dict()
+PLUGINS = dict()  #: Collection of builtin plugins
 
 
 TypeT = TypeVar("TypeT", bound=Type[Any])
diff --git a/lpcraft/plugins/plugins.py b/lpcraft/plugins/plugins.py
index 9aa7a4f..032cf8e 100644
--- a/lpcraft/plugins/plugins.py
+++ b/lpcraft/plugins/plugins.py
@@ -3,6 +3,8 @@
 
 from __future__ import annotations
 
+__all__ = ["ToxPlugin"]
+
 from lpcraft.config import Job
 from lpcraft.plugin import hookimpl
 from lpcraft.plugins import register
@@ -10,6 +12,13 @@ from lpcraft.plugins import register
 
 @register(name="tox")
 class ToxPlugin:
+    """Installs `tox` and executes the configured environments.
+
+    Usage:
+        In `.launchpad.yaml` create a key/value pair with `plugin` and `tox`
+        within the job definition.
+    """
+
     # XXX jugmac00 2021-12-16: this plugin is not yet fully implemented
     def __init__(self, config: Job) -> None:
         self.config = config