docs: Explain use of auto-provisioning for required plugins

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

docs/installation.rst

@@ -2,10 +2,10 @@ Installation
 ============
 
 As tool
---------
+-------
 
 :pypi:`tox` is a CLI tool that needs a Python interpreter (version 3.9 or higher) to run. We recommend either
-:pypi:`pipx` or  :pypi:`uv` to install tox into an isolated environment. This has the added benefit that later you'll
+:pypi:`pipx` or :pypi:`uv` to install tox into an isolated environment. This has the added benefit that later you'll
 be able to upgrade tox without affecting other parts of the system. We provide method for ``pip`` too here but we
 discourage that path if you can:
 
@@ -17,7 +17,6 @@ discourage that path if you can:
         uv tool install tox
         tox --help
 
-
 .. tab:: pipx
 
     .. code-block:: bash
@@ -40,6 +39,7 @@ discourage that path if you can:
 
 wheel
 ~~~~~
+
 Installing tox via a wheel (default with pip) requires an installer that can understand the ``python-requires`` tag (see
 :pep:`503`), with pip this is version ``9.0.0`` (released in November 2016). Furthermore, in case you're not installing
 it via PyPI you need to use a mirror that correctly forwards the ``python-requires`` tag (notably the OpenStack mirrors
@@ -49,19 +49,22 @@ don't do this, or older :gh_repo:`devpi/devpi` versions - added with version ``4
 
 sdist
 ~~~~~
+
 When installing via a source distribution you need an installer that handles the :pep:`517` specification. In case of
 ``pip`` this is version ``18.0.0`` or later (released in July 2018). If you cannot upgrade your pip to support this you
 need to ensure that the build requirements from :gh:`pyproject.toml <tox-dev/tox/blob/main/pyproject.toml>` are
 satisfied before triggering the installation.
 
 via ``setup.py``
 ----------------
+
 We don't recommend and officially support this method. You should prefer using an installer that supports :pep:`517`
 interface, such as pip ``19.0.0`` or later. That being said you might be able to still install a package via this method
 if you satisfy build dependencies before calling the installation command (as described under :ref:`sdist`).
 
 latest unreleased
 -----------------
+
 Installing an unreleased version is discouraged and should be only done for testing purposes. If you do so you'll need
 a pip version of at least ``18.0.0`` and use the following command:
 

docs/plugins.rst

@@ -1,5 +1,37 @@
-Extending tox
-=============
+Plugins
+=======
+
+Many plugins are available for tox. These includes, but are not limited to, the extensions found on the ``tox-dev`` org
+on ':gh:`GitHub <tox-dev>`.
+
+Plugins are automatically discovered once from the Python environment that tox itself is installed in. This means that
+if tox is installed in an isolated environment (e.g. when installed using :pypi:`pipx` or :pypi:`uv`), the plugin(s)
+must be installed in the same environment. To ensure a plugin is always available, you can include the plugin is listed
+in :ref:`requires`, which will cause tox to auto-provision a new isolated environment with both tox and the plugin(s)
+installed. For example:
+
+.. tab:: TOML
+
+   .. code-block:: toml
+
+        requires = ["tox>=4", "tox-uv>=1"]
+
+.. tab:: INI
+
+   .. code-block:: ini
+
+        [tox]
+        requires =
+            tox>=4
+            tox-uv>=1
+
+For more information, refer to :ref:`the user guide <auto-provisioning>`.
+
+Developing your own plugin
+--------------------------
+
+The below provides some guidance on how to develop your own plugin for tox. A reference guide to the plugin API can be
+found in :doc:`plugins_api`.
 
 Extensions points
 ~~~~~~~~~~~~~~~~~
@@ -50,20 +82,24 @@ How to apply:
 
 Migration from tox 3
 ~~~~~~~~~~~~~~~~~~~~
+
 This section explains how the plugin interface changed between tox 3 and 4, and provides guidance for plugin developers
 on how to migrate.
 
 ``tox_get_python_executable``
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 With tox 4 the Python discovery is performed ``tox.tox_env.python.virtual_env.api._get_python`` that delegates the job
 to ``virtualenv``. Therefore first `define a new virtualenv discovery mechanism
 <https://virtualenv.pypa.io/en/latest/extend.html#python-discovery>`_ and then set that by setting the
 ``VIRTUALENV_DISCOVERY`` environment variable.
 
 ``tox_package``
----------------
+^^^^^^^^^^^^^^^
+
 Register new packager types via :func:`tox_register_tox_env <tox.plugin.spec.tox_register_tox_env>`.
 
 ``tox_addoption``
------------------
+^^^^^^^^^^^^^^^^^
+
 Renamed to :func:`tox_add_option <tox.plugin.spec.tox_add_option>`.

docs/user_guide.rst

@@ -382,6 +382,7 @@ you want to do more research, we recommend taking a look at these projects:
 - `Invoke <https://www.pyinvoke.org/>`__ is a general-purpose task execution library, similar to Make. Invoke is far
   more general-purpose than tox but it does not contain the Python testing-specific features that tox specializes in.
 
+.. _auto-provisioning:
 
 Auto-provisioning
 -----------------