doc/tmpdir: significantly reduce space dedicated to tmpdir/tmpdir_factory

Emphasize tmp_path/tmp_path_factory and just note the legacy ones.

doc/en/how-to/tmpdir.rst

@@ -8,14 +8,11 @@ How to use temporary directories and files in tests
 The ``tmp_path`` fixture
 ------------------------
 
-
-
-
 You can use the ``tmp_path`` fixture which will
 provide a temporary directory unique to the test invocation,
 created in the `base temporary directory`_.
 
-``tmp_path`` is a ``pathlib.Path`` object. Here is an example test usage:
+``tmp_path`` is a :class:`pathlib.Path` object. Here is an example test usage:
 
 .. code-block:: python
 
@@ -71,82 +68,12 @@ Running this would result in a passed test except for the last
 The ``tmp_path_factory`` fixture
 --------------------------------
 
-
-
-
 The ``tmp_path_factory`` is a session-scoped fixture which can be used
 to create arbitrary temporary directories from any other fixture or test.
 
-It is intended to replace ``tmpdir_factory``, and returns :class:`pathlib.Path` instances.
-
-See :ref:`tmp_path_factory API <tmp_path_factory factory api>` for details.
-
-
-The 'tmpdir' fixture
---------------------
-
-You can use the ``tmpdir`` fixture which will
-provide a temporary directory unique to the test invocation,
-created in the `base temporary directory`_.
-
-``tmpdir`` is a `py.path.local`_ object which offers ``os.path`` methods
-and more.  Here is an example test usage:
-
-.. code-block:: python
-
-    # content of test_tmpdir.py
-    def test_create_file(tmpdir):
-        p = tmpdir.mkdir("sub").join("hello.txt")
-        p.write("content")
-        assert p.read() == "content"
-        assert len(tmpdir.listdir()) == 1
-        assert 0
-
-Running this would result in a passed test except for the last
-``assert 0`` line which we use to look at values:
-
-.. code-block:: pytest
-
-    $ pytest test_tmpdir.py
-    =========================== test session starts ============================
-    platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y
-    cachedir: $PYTHON_PREFIX/.pytest_cache
-    rootdir: $REGENDOC_TMPDIR
-    collected 1 item
-
-    test_tmpdir.py F                                                     [100%]
-
-    ================================= FAILURES =================================
-    _____________________________ test_create_file _____________________________
-
-    tmpdir = local('PYTEST_TMPDIR/test_create_file0')
-
-        def test_create_file(tmpdir):
-            p = tmpdir.mkdir("sub").join("hello.txt")
-            p.write("content")
-            assert p.read() == "content"
-            assert len(tmpdir.listdir()) == 1
-    >       assert 0
-    E       assert 0
-
-    test_tmpdir.py:6: AssertionError
-    ========================= short test summary info ==========================
-    FAILED test_tmpdir.py::test_create_file - assert 0
-    ============================ 1 failed in 0.12s =============================
-
-.. _`tmpdir factory example`:
-
-The 'tmpdir_factory' fixture
-----------------------------
-
-
-
-The ``tmpdir_factory`` is a session-scoped fixture which can be used
-to create arbitrary temporary directories from any other fixture or test.
-
 For example, suppose your test suite needs a large image on disk, which is
 generated procedurally. Instead of computing the same image for each test
-that uses it into its own ``tmpdir``, you can generate it once per-session
+that uses it into its own ``tmp_path``, you can generate it once per-session
 to save time:
 
 .. code-block:: python
@@ -156,10 +83,10 @@ to save time:
 
 
     @pytest.fixture(scope="session")
-    def image_file(tmpdir_factory):
+    def image_file(tmp_path_factory):
         img = compute_expensive_image()
-        fn = tmpdir_factory.mktemp("data").join("img.png")
+        fn = tmp_path_factory.mktemp("data") / "img.png"
-        img.save(str(fn))
+        img.save(fn)
         return fn
 
 
@@ -168,7 +95,20 @@ to save time:
         img = load_image(image_file)
         # compute and test histogram
 
-See :ref:`tmpdir_factory API <tmpdir factory api>` for details.
+See :ref:`tmp_path_factory API <tmp_path_factory factory api>` for details.
+
+.. _`tmpdir and tmpdir_factory`:
+
+The ``tmpdir`` and ``tmpdir_factory`` fixtures
+---------------------------------------------------
+
+The ``tmpdir`` and ``tmpdir_factory`` fixtures are similar to ``tmp_path``
+and ``tmp_path_factory``, but use/return legacy `py.path.local`_ objects
+rather than standard :class:`pathlib.Path` objects. These days, prefer to
+use ``tmp_path`` and ``tmp_path_factory``.
+
+See :fixture:`tmpdir <tmpdir>` :fixture:`tmpdir_factory <tmpdir_factory>`
+API for details.
 
 
 .. _`base temporary directory`:

doc/en/reference/reference.rst

@@ -582,7 +582,7 @@ tmp_path
     :no-auto-options:
 
 
-.. fixture:: _pytest.tmpdir.tmp_path_factory
+.. fixture:: tmp_path_factory
 
 tmp_path_factory
 ~~~~~~~~~~~~~~~~
@@ -601,7 +601,7 @@ tmp_path_factory
 tmpdir
 ~~~~~~
 
-:ref:`tmpdir`
+:ref:`tmpdir and tmpdir_factory`
 
 .. autofunction:: _pytest.tmpdir.tmpdir()
     :no-auto-options:
@@ -612,9 +612,7 @@ tmpdir
 tmpdir_factory
 ~~~~~~~~~~~~~~
 
-:ref:`tmpdir factory example`
+:ref:`tmpdir and tmpdir_factory`
-
-.. _`tmpdir factory api`:
 
 ``tmp_path_factory`` is an instance of :class:`~pytest.TempdirFactory`: