docs(plugin): explain plugin registration #3116

hashar · 2023-09-07T12:23:38Z

In the legacy branch, the plugin documentation described plugins get discovered by being in the same environment. That documentation was not ported to the new branch. The doc was originally added by hff7143e7c991b1a80e7ec1ea6836ef3a21b5a812

Notably https://tox.wiki/en/3.27.1/plugins.html#using-plugins had:

To start using a plugin you need to install it in the same environment where the tox host is installed.

Which gives a hint.

I also wondered how the discoverability works via Pluggy, that is done by having the plugin to register a tox entry-point which allows tox to find the plugin module. Document that.

While writing a plugin, that would have helped me find out how to install or enable it when it is indeed automatic (as long as a tox entry-point is defined by the plugin).

ran the linter to address style issues (tox -e fix)
wrote descriptive pull request text
ensured there are test(s) validating the fix (documentation only, so not applicable?)
added news fragment in docs/changelog folder (~~not sure whether it is worth mentioning~~, turns out that is required by CI)
updated/extended the documentation

gaborbernat · 2023-09-07T21:04:47Z

src/tox/plugin/__init__.py

+tox uses `pluggy <https://pluggy.readthedocs.io/en/stable/>`_ 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:



Please realing to 120 characters length.

Ooops, I have realigned to 120 characters.

In the legacy branch, the plugin documentation described plugins get discovered by being in the same environment. That documentation was not ported to the new branch. The doc was originally added by hff7143e7c991b1a80e7ec1ea6836ef3a21b5a812 I also wondered how the discoverability works via Pluggy, that is done by having the plugin to register a `tox` entry-point which allows tox to find the plugin module. Document that. While writing a plugin, that would have helped me find out how to install or enable it when it is indeed automatic (as long as a tox entry-point is defined by the plugin).

gaborbernat

hashar requested a review from gaborbernat as a code owner September 7, 2023 12:23

hashar force-pushed the docs-plugin-discoverability branch from 8b4f87d to e6373a2 Compare September 7, 2023 12:26

psf-chronographer bot added the bot:chronographer:provided label Sep 7, 2023

gaborbernat requested changes Sep 7, 2023

View reviewed changes

hashar force-pushed the docs-plugin-discoverability branch from e6373a2 to 655a7b6 Compare September 8, 2023 07:38

gaborbernat approved these changes Sep 8, 2023

View reviewed changes

gaborbernat merged commit 381e37a into tox-dev:main Sep 8, 2023

hashar deleted the docs-plugin-discoverability branch September 12, 2023 20:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(plugin): explain plugin registration #3116

docs(plugin): explain plugin registration #3116

hashar commented Sep 7, 2023 •

edited

Loading

gaborbernat Sep 7, 2023

hashar Sep 8, 2023

gaborbernat left a comment

docs(plugin): explain plugin registration #3116

docs(plugin): explain plugin registration #3116

Conversation

hashar commented Sep 7, 2023 • edited Loading

gaborbernat Sep 7, 2023

Choose a reason for hiding this comment

hashar Sep 8, 2023

Choose a reason for hiding this comment

gaborbernat left a comment

Choose a reason for hiding this comment

hashar commented Sep 7, 2023 •

edited

Loading