extend docs with basics about tmp_path and tmp_path_facotry

doc/en/tmpdir.rst

@@ -5,6 +5,51 @@
 Temporary directories and files
 ================================================
 
+The ``tmp_path`` fixture
+----------------------
+
+.. versionadded:: 3.9
+
+
+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 `pathlib/pathlib2.Path`_ object. Here is an example test usage::
+
+    # content of test_tmp_path.py
+    import os
+    CONTENT = u"content"
+
+    def test_create_file(tmp_path):
+        d = tmp_path / "sub"
+        d.mkdir()
+        p = d / "hello.txt"
+        p.write_text(CONTENT)
+        assert p.read_text() == 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::
+
+    $ pytest test_tmp_path.py
+    ... #fill fom regendoc
+
+
+
+The ``tmp_path_facotry`` fixture
+------------------------------
+
+.. versionadded:: 3.9
+
+
+The ``tmp_path_facotry`` is a session-scoped fixture which can be used
+to create arbitrary temporary directories from any other fixture or test.
+
+its intended to replace ``tmpdir_factory``
+
+
 The 'tmpdir' fixture
 --------------------