Merge pull request #10213 from pytest-dev/backport-10192-to-7.1.x

Author: nicoddemus

src/_pytest/monkeypatch.py

@@ -29,21 +29,25 @@
 def monkeypatch() -> Generator["MonkeyPatch", None, None]:
     """A convenient fixture for monkey-patching.
 
-    The fixture provides these methods to modify objects, dictionaries or
-    os.environ::
-
-        monkeypatch.setattr(obj, name, value, raising=True)
-        monkeypatch.delattr(obj, name, raising=True)
-        monkeypatch.setitem(mapping, name, value)
-        monkeypatch.delitem(obj, name, raising=True)
-        monkeypatch.setenv(name, value, prepend=None)
-        monkeypatch.delenv(name, raising=True)
-        monkeypatch.syspath_prepend(path)
-        monkeypatch.chdir(path)
+    The fixture provides these methods to modify objects, dictionaries, or
+    :data:`os.environ`:
+
+    * :meth:`monkeypatch.setattr(obj, name, value, raising=True) <pytest.MonkeyPatch.setattr>`
+    * :meth:`monkeypatch.delattr(obj, name, raising=True) <pytest.MonkeyPatch.delattr>`
+    * :meth:`monkeypatch.setitem(mapping, name, value) <pytest.MonkeyPatch.setitem>`
+    * :meth:`monkeypatch.delitem(obj, name, raising=True) <pytest.MonkeyPatch.delitem>`
+    * :meth:`monkeypatch.setenv(name, value, prepend=None) <pytest.MonkeyPatch.setenv>`
+    * :meth:`monkeypatch.delenv(name, raising=True) <pytest.MonkeyPatch.delenv>`
+    * :meth:`monkeypatch.syspath_prepend(path) <pytest.MonkeyPatch.syspath_prepend>`
+    * :meth:`monkeypatch.chdir(path) <pytest.MonkeyPatch.chdir>`
 
     All modifications will be undone after the requesting test function or
-    fixture has finished. The ``raising`` parameter determines if a KeyError
-    or AttributeError will be raised if the set/deletion operation has no target.
+    fixture has finished. The ``raising`` parameter determines if a :class:`KeyError`
+    or :class:`AttributeError` will be raised if the set/deletion operation does not have the
+    specified target.
+
+    To undo modifications done by the fixture in a contained scope,
+    use :meth:`context() <pytest.MonkeyPatch.context>`.
     """
     mpatch = MonkeyPatch()
     yield mpatch
@@ -353,11 +357,14 @@ def undo(self) -> None:
         There is generally no need to call `undo()`, since it is
         called automatically during tear-down.
 
-        Note that the same `monkeypatch` fixture is used across a
-        single test function invocation. If `monkeypatch` is used both by
-        the test function itself and one of the test fixtures,
-        calling `undo()` will undo all of the changes made in
-        both functions.
+        .. note::
+            The same `monkeypatch` fixture is used across a
+            single test function invocation. If `monkeypatch` is used both by
+            the test function itself and one of the test fixtures,
+            calling `undo()` will undo all of the changes made in
+            both functions.
+
+            Prefer to use :meth:`context() <pytest.MonkeyPatch.context>` instead.
         """
         for obj, name, value in reversed(self._setattr):
             if value is not notset: