Skip to content

Commit 381e37a

Browse files
authored
docs(plugin): explain plugin registration (#3116)
1 parent 1371e98 commit 381e37a

File tree

2 files changed

+16
-2
lines changed

2 files changed

+16
-2
lines changed

docs/changelog/3116.doc.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Explain how plugins are registered and discovered - by :user:`hashar`.

src/tox/plugin/__init__.py

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
11
"""
2-
tox uses `pluggy <https://pluggy.readthedocs.io/en/stable/>`_ to customize the default behaviour. For example the
3-
following code snippet would define a new ``--magic`` command line interface flag the user can specify:
2+
tox uses `pluggy <https://pluggy.readthedocs.io/en/stable/>`_ to customize the default behaviour. It provides an
3+
extension mechanism for plugin management an calling hooks.
4+
5+
Pluggy discovers a plugin by looking up for entry-points named ``tox``, for example in a pyproject.toml:
6+
7+
.. code-block:: toml
8+
9+
[project.entry-points.tox]
10+
your_plugin = "your_plugin.hooks"
11+
12+
Therefore, to start using a plugin, you solely need to install it in the same environment tox is running in and it will
13+
be discovered via the defined entry-point (in the example above, tox will load ``your_plugin.hooks``).
14+
15+
A plugin is created by implementing extension points in the form of hooks. For example the following code snippet would
16+
define a new ``--magic`` command line interface flag the user can specify:
417
518
.. code-block:: python
619

0 commit comments

Comments
 (0)