[docs] Document how to require a plugin (#3552)

* docs: Allow version_deprecated option

We also remove the unused 'version_changed' option.

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

* tox: Soft-deprecate '[tox] min_version'

We don't raise a warning or similar: this is purely to encourage new
users (and existing users reworking their tox.ini files) to prefer
'[tox] requires'.

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

* docs: Explain use of auto-provisioning for required plugins

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

---------

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

Author: stephenfin

docs/changelog/3553.doc.rst

@@ -0,0 +1 @@
+The ``min_version``/``minversion`` config option is deprecated in favor of the ``requires`` option.

docs/config.rst

@@ -46,7 +46,8 @@ For example:
 .. code-block:: ini
 
     [tox]
-    min_version = 4.20
+    requires =
+        tox >= 4.20
     env_list =
         3.13
         3.12
@@ -74,7 +75,8 @@ This configuration file uses:
 .. code-block:: ini
 
     [tox:tox]
-    min_version = 4.0
+    requires =
+        tox >= 4.0
     env_list =
         3.13
         3.12
@@ -98,7 +100,8 @@ instead inside the ``pyproject.toml`` file under the ``tool.tox`` table and ``le
     [tool.tox]
     legacy_tox_ini = """
         [tox]
-        min_version = 4.0
+        requires =
+            tox >= 4.0
         env_list =
             py310
             py39
@@ -203,6 +206,9 @@ The following options are set in the ``[tox]`` section of ``tox.ini`` or the ``[
 .. conf::
    :keys: min_version, minversion
    :default: <current version of tox>
+   :version_deprecated: 4.28.0
+
+   **DEPRECATED** Prefer requiring a minimum tox version via :ref:`requires`.
 
    A string to define the minimal tox version required to run. If the host's tox version is less than this, it will
    automatically create a provisioned tox environment that satisfies this requirement. See :ref:`provision_tox_env`

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 include, 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/tox_conf.py

@@ -24,7 +24,7 @@ class ToxConfig(SphinxDirective):
     option_spec: Final[ClassVar[dict[str, Any]]] = {
         "keys": unchanged_required,
         "version_added": unchanged,
-        "version_changed": unchanged,
+        "version_deprecated": unchanged,
         "default": unchanged,
         "constant": flag,
         "ref_suffix": unchanged,
@@ -71,6 +71,10 @@ def run(self) -> list[Node]:
             line += Text(" 📢 added in ")
             ver = self.options["version_added"]
             line += literal(ver, ver)
+        if "version_deprecated" in self.options:
+            line += Text(" ⚠️ deprecated in ")
+            ver = self.options["version_deprecated"]
+            line += literal(ver, ver)
 
         p = container("")
         self.state.nested_parse(StringList(string2lines("\n".join(f"    {i}" for i in self.content))), 0, p)

docs/upgrading.rst

@@ -321,6 +321,6 @@ version is above the version this feature was added to it, for example for setup
 Provisioning environment
 ------------------------
 
-The provisioning environment is triggered when ``minversion`` or ``requires`` are specified and the current environment
+The provisioning environment is triggered when ``min_version`` or ``requires`` are specified and the current environment
 does not satisfy the requirement. In tox 4, the provisioning environment (``.tox`` by default) must be explicitly
 configured and will not inherit values from ``[testenv]`` section.

docs/user_guide.rst

@@ -382,10 +382,12 @@ 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
 -----------------
-In case the installed tox version does not satisfy either the :ref:`min_version` or the :ref:`requires`, tox will automatically
+
+In case the installed tox version does not satisfy either the :ref:`requires` or the :ref:`min_version`, tox will automatically
 create a virtual environment under :ref:`provision_tox_env` name that satisfies those constraints and delegate all
 calls to this meta environment. This should allow satisfying constraints on your tox environment automatically,
 given you have at least version ``3.8.0`` of tox.
@@ -396,17 +398,16 @@ For example given:
 
    .. code-block:: toml
 
-        min_version = "4"
-        requires = ["tox-uv>=1"]
+        requires = ["tox>=4", "tox-uv>=1"]
 
 .. tab:: INI
 
    .. code-block:: ini
 
         [tox]
-        min_version = 4
-        requires = tox-uv>=1
-
+        requires =
+            tox>=4
+            tox-uv>=1
 
 if the user runs it with tox ``3.8`` or later the installed tox application will automatically ensure that both the minimum version and
 requires constraints are satisfied, by creating a virtual environment under ``.tox`` folder, and then installing into it