diff --git a/docs/changelog/3116.doc.rst b/docs/changelog/3116.doc.rst new file mode 100644 index 0000000000..c98f0845ee --- /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 6565ea588f..5cb5593199 100644 --- a/src/tox/plugin/__init__.py +++ b/src/tox/plugin/__init__.py @@ -1,6 +1,22 @@ """ -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 @@ -12,8 +28,9 @@ def tox_add_option(parser: ToxParser) -> None: parser.add_argument("--magic", action="store_true", help="magical flag") -You can define such hooks either in a package installed alongside tox or within a ``toxfile.py`` found alongside your -tox configuration file (root of your project). +You can define such hooks either in a package installed alongside tox or within +a ``toxfile.py`` found alongside your tox configuration file (root of your +project). """ from __future__ import annotations