Explicit note that tmpdir fixture is discouraged in favour of tmp_path #9937 (#10138)

Co-authored-by: Bruno Oliveira <nicoddemus@gmail.com>
Co-authored-by: kevin.hierro-ext <kevin.hierro-ext@clarity.ai>
Co-authored-by: Dani Sancas <lord.sancas@gmail.com>

src/_pytest/legacypath.py

@@ -271,7 +271,14 @@ class LegacyTestdirPlugin:
 @attr.s(init=False, auto_attribs=True)
 class TempdirFactory:
     """Backward compatibility wrapper that implements :class:`py.path.local`
-    for :class:`TempPathFactory`."""
+    for :class:`TempPathFactory`.
+
+    .. note::
+        These days, it is preferred to use ``tmp_path_factory``.
+
+        :ref:`About the tmpdir and tmpdir_factory fixtures<tmpdir and tmpdir_factory>`.
+
+    """
 
     _tmppath_factory: TempPathFactory
 
@@ -312,6 +319,11 @@ class LegacyTmpdirPlugin:
 
         The returned object is a `legacy_path`_ object.
 
+        .. note::
+            These days, it is preferred to use ``tmp_path``.
+
+            :ref:`About the tmpdir and tmpdir_factory fixtures<tmpdir and tmpdir_factory>`.
+
         .. _legacy_path: https://py.readthedocs.io/en/latest/path.html
         """
         return legacy_path(tmp_path)