launchpad-reviewers team mailing list archive

[Jürgen Gmach <mp+413668@xxxxxxxxxxxxxxxxxx>]

Jürgen Gmach has proposed merging ~jugmac00/lpcraft:create-documentation-for-plugin-system into lpcraft:main.

Commit message:
Create documentation for the plugin system

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~jugmac00/lpcraft/+git/lpcraft/+merge/413668
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/lpcraft:create-documentation-for-plugin-system into lpcraft:main.

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..320cd76 100644
--- a/lpcraft/plugin/__init__.py
+++ b/lpcraft/plugin/__init__.py
@@ -3,4 +3,10 @@
 
 import pluggy
 
-hookimpl = pluggy.HookimplMarker("lpcraft")
+NAME = "lpcraft"  #: name of the hook
+
+hookimpl = pluggy.HookimplMarker(
+    NAME
+)  #: decorator to mark lpcraft plugin hooks
+
+__all__ = ["NAME", "hookimpl"]
diff --git a/lpcraft/plugin/hookspecs.py b/lpcraft/plugin/hookspecs.py
index e1232f4..802df6c 100644
--- a/lpcraft/plugin/hookspecs.py
+++ b/lpcraft/plugin/hookspecs.py
@@ -5,7 +5,9 @@ from __future__ import annotations
 
 import pluggy
 
-hookspec = pluggy.HookspecMarker("lpcraft")
+from lpcraft.plugin import NAME
+
+hookspec = pluggy.HookspecMarker(NAME)
 
 
 @hookspec  # type: ignore
@@ -32,3 +34,11 @@ def lpcraft_set_environment() -> dict[str, str | None]:
     # Please note: when there is the same environment variable provided by
     # the plugin and the configuration file, the one in the configuration
     # file will be taken into account
+
+
+__all__ = [
+    "lpcraft_install_packages",
+    "lpcraft_install_snaps",
+    "lpcraft_execute_run",
+    "lpcraft_set_environment",
+]
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..0ea2acf 100644
--- a/lpcraft/plugins/plugins.py
+++ b/lpcraft/plugins/plugins.py
@@ -10,6 +10,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
@@ -28,3 +35,6 @@ class ToxPlugin:
         # necessary. Let's remove this once we have a plugin which actually
         # needs to set environment variables.
         return {"PLUGIN": "tox"}
+
+
+__all__ = ["ToxPlugin"]