Issue #10829 Improve docs on basetemp and retention

Improve coverage of current handling of `--basetemp` option and its lack
of retention functionality.

changelog/10829.doc.rst

@@ -0,0 +1 @@
+Improve documentation on the current handling of the ``--basetemp`` option and its lack of retention functionality (:ref:`temporary directory location and retention`).

doc/en/how-to/tmp_path.rst

@@ -133,27 +133,47 @@ API for details.
 Temporary directory location and retention
 ------------------------------------------
 
-Temporary directories are by default created as sub-directories of
-the system temporary directory.  The base name will be ``pytest-NUM`` where
-``NUM`` will be incremented with each test run.
-By default, entries older than 3 temporary directories will be removed.
-This behavior can be configured with :confval:`tmp_path_retention_count` and
-:confval:`tmp_path_retention_policy`.
+The temporary directories,
+as returned by the :fixture:`tmp_path` and (now deprecated) :fixture:`tmpdir` fixtures,
+are automatically created under a base temporary directory,
+in a structure that depends on the ``--basetemp`` option:
 
-Using the ``--basetemp``
-option will remove the directory before every run, effectively meaning the temporary directories
-of only the most recent run will be kept.
+- By default (when the ``--basetemp`` option is not set),
+  the temporary directories will follow this this template:
 
-You can override the default temporary directory setting like this:
+  .. code-block:: text
 
-.. code-block:: bash
+      {temproot}/pytest-of-{user}/pytest-{num}/{testname}/
 
-    pytest --basetemp=mydir
+  where:
 
-.. warning::
+  - ``{temproot}`` is the system temporary directory
+    as determined by :py:func:`tempfile.gettempdir`.
+    It can be overridden by the ``PYTEST_DEBUG_TEMPROOT`` environment variable.
+  - ``{user}`` is the user name running the tests,
+  - ``{num}`` is a number that is incremented with each test suite run
+  - ``{testname}`` is a sanitized version of :py:attr:`the name of the current test <_pytest.nodes.Node.name>`.
 
-    The contents of ``mydir`` will be completely removed, so make sure to use a directory
-    for that purpose only.
+  The auto-incrementing ``{num}`` placeholder provides a basic retention feature
+  and avoids that existing results of previous test runs are blindly removed.
+  By default, the last 3 temporary directories are kept,
+  but this behavior can be configured with
+  :confval:`tmp_path_retention_count` and :confval:`tmp_path_retention_policy`.
+
+- When the ``--basetemp`` option is used (e.g. ``pytest --basetemp=mydir``),
+  it will be used directly as base temporary directory:
+
+  .. code-block:: text
+
+      {basetemp}/{testname}/
+
+  Note that there is no retention feature in this case:
+  only the results of the most recent run will be kept.
+
+  .. warning::
+
+      The directory given to ``--basetemp`` will be cleared blindly before each test run,
+      so make sure to use a directory for that purpose only.
 
 When distributing tests on the local machine using ``pytest-xdist``, care is taken to
 automatically configure a `basetemp` directory for the sub processes such that all temporary

src/_pytest/legacypath.py

@@ -304,16 +304,11 @@ def tmpdir_factory(request: FixtureRequest) -> TempdirFactory:
     @staticmethod
     @fixture
     def tmpdir(tmp_path: Path) -> LEGACY_PATH:
-        """Return a temporary directory path object which is unique to each test
-        function invocation, created as a sub directory of the base temporary
-        directory.
-
-        By default, a new base temporary directory is created each test session,
-        and old bases are removed after 3 sessions, to aid in debugging. If
-        ``--basetemp`` is used then it is cleared each session. See
-        :ref:`temporary directory location and retention`.
-
-        The returned object is a `legacy_path`_ object.
+        """Return a temporary directory (as `legacy_path`_ object)
+        which is unique to each test function invocation.
+        The temporary directory is created as a subdirectory
+        of the base temporary directory, with configurable retention,
+        as discussed in :ref:`temporary directory location and retention`.
 
         .. note::
             These days, it is preferred to use ``tmp_path``.

src/_pytest/tmpdir.py

@@ -41,9 +41,8 @@
 @final
 @dataclasses.dataclass
 class TempPathFactory:
-    """Factory for temporary directories under the common base temp directory.
-
-    The base directory can be configured using the ``--basetemp`` option.
+    """Factory for temporary directories under the common base temp directory,
+    as discussed at :ref:`temporary directory location and retention`.
     """
 
     _given_basetemp: Path | None
@@ -257,18 +256,11 @@ def _mk_tmp(request: FixtureRequest, factory: TempPathFactory) -> Path:
 def tmp_path(
     request: FixtureRequest, tmp_path_factory: TempPathFactory
 ) -> Generator[Path]:
-    """Return a temporary directory path object which is unique to each test
-    function invocation, created as a sub directory of the base temporary
-    directory.
-
-    By default, a new base temporary directory is created each test session,
-    and old bases are removed after 3 sessions, to aid in debugging.
-    This behavior can be configured with :confval:`tmp_path_retention_count` and
-    :confval:`tmp_path_retention_policy`.
-    If ``--basetemp`` is used then it is cleared each session. See
-    :ref:`temporary directory location and retention`.
-
-    The returned object is a :class:`pathlib.Path` object.
+    """Return a temporary directory (as :class:`pathlib.Path` object)
+    which is unique to each test function invocation.
+    The temporary directory is created as a subdirectory
+    of the base temporary directory, with configurable retention,
+    as discussed in :ref:`temporary directory location and retention`.
     """
     path = _mk_tmp(request, tmp_path_factory)
     yield path