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