From 739322af037459a8bb9b32e32690b67850573bb6 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Date: Sat, 13 Aug 2022 21:07:27 +0200
Subject: [PATCH] Mention `monkeypatch.context()` in the docs (#10192)

In addition:

* Improve the docs a bit with links.
* Recommend `context()` instead of `undo()`.
---
 src/_pytest/monkeypatch.py | 41 ++++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/src/_pytest/monkeypatch.py b/src/_pytest/monkeypatch.py
index 91d590fb3..f29c4f2ef 100644
--- a/src/_pytest/monkeypatch.py
+++ b/src/_pytest/monkeypatch.py
@@ -29,21 +29,25 @@ V = TypeVar("V")
 def monkeypatch() -> Generator["MonkeyPatch", None, None]:
     """A convenient fixture for monkey-patching.
 
-    The fixture provides these methods to modify objects, dictionaries or
-    os.environ::
+    The fixture provides these methods to modify objects, dictionaries, or
+    :data:`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)
+    * :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 @@ class MonkeyPatch:
         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: