From 381e37aa9205686ea1276e94c1955d128c7a5146 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Fri, 8 Sep 2023 16:44:23 +0200 Subject: [PATCH] docs(plugin): explain plugin registration (#3116) --- docs/changelog/3116.doc.rst | 1 + src/tox/plugin/__init__.py | 17 +++++++++++++++-- 2 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 docs/changelog/3116.doc.rst diff --git a/docs/changelog/3116.doc.rst b/docs/changelog/3116.doc.rst new file mode 100644 index 000000000..c98f0845e --- /dev/null +++ b/docs/changelog/3116.doc.rst @@ -0,0 +1 @@ +Explain how plugins are registered and discovered - by :user:`hashar`. diff --git a/src/tox/plugin/__init__.py b/src/tox/plugin/__init__.py index 6565ea588..d222695a7 100644 --- a/src/tox/plugin/__init__.py +++ b/src/tox/plugin/__init__.py @@ -1,6 +1,19 @@ """ -tox uses `pluggy `_ to customize the default behaviour. For example the -following code snippet would define a new ``--magic`` command line interface flag the user can specify: +tox uses `pluggy `_ to customize the default behaviour. It provides an +extension mechanism for plugin management an calling hooks. + +Pluggy discovers a plugin by looking up for entry-points named ``tox``, for example in a pyproject.toml: + +.. code-block:: toml + + [project.entry-points.tox] + your_plugin = "your_plugin.hooks" + +Therefore, to start using a plugin, you solely need to install it in the same environment tox is running in and it will +be discovered via the defined entry-point (in the example above, tox will load ``your_plugin.hooks``). + +A plugin is created by implementing extension points in the form of hooks. For example the following code snippet would +define a new ``--magic`` command line interface flag the user can specify: .. code-block:: python