Remove outdated docs about pytest.warns and DeprecatedWarning

Since #2908, the user doesn't need to set warning filters to capture
`DeprecationWarning` with `pytest.warns`.

Fix #8666

doc/en/how-to/capture-warnings.rst

@@ -173,8 +173,6 @@ DeprecationWarning and PendingDeprecationWarning
 ------------------------------------------------
 
 
-
-
 By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning`` warnings from
 user code and third-party libraries, as recommended by `PEP-0565 <https://www.python.org/dev/peps/pep-0565>`_.
 This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed.
@@ -230,27 +228,8 @@ that a certain function call triggers a ``DeprecationWarning`` or
 This test will fail if ``myfunction`` does not issue a deprecation warning
 when called with a ``17`` argument.
 
-By default, ``DeprecationWarning`` and ``PendingDeprecationWarning`` will not be
-caught when using :func:`pytest.warns` or :ref:`recwarn <recwarn>` because
-the default Python warnings filters hide
-them. If you wish to record them in your own code, use
-``warnings.simplefilter('always')``:
-
-.. code-block:: python
-
-    import warnings
-    import pytest
 
 
-    def test_deprecation(recwarn):
-        warnings.simplefilter("always")
-        myfunction(17)
-        assert len(recwarn) == 1
-        assert recwarn.pop(DeprecationWarning)
-
-
-The :ref:`recwarn <recwarn>` fixture automatically ensures to reset the warnings
-filter at the end of the test, so no global state is leaked.
 
 .. _`asserting warnings`:
 
@@ -317,9 +296,9 @@ additional information:
 Alternatively, you can examine raised warnings in detail using the
 :ref:`recwarn <recwarn>` fixture (see below).
 
-.. note::
+
-    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
+The :ref:`recwarn <recwarn>` fixture automatically ensures to reset the warnings
-    differently; see :ref:`ensuring_function_triggers`.
+filter at the end of the test, so no global state is leaked.
 
 .. _`recording warnings`:
 

testing/test_recwarn.py

@@ -27,6 +27,17 @@ def test_recwarn_functional(pytester: Pytester) -> None:
     reprec.assertoutcome(passed=1)
 
 
+@pytest.mark.filterwarnings("")
+def test_recwarn_captures_deprecation_warning(recwarn: WarningsRecorder) -> None:
+    """
+    Check that recwarn can capture DeprecationWarning by default
+    without custom filterwarnings (see #8666).
+    """
+    warnings.warn(DeprecationWarning("some deprecation"))
+    assert len(recwarn) == 1
+    assert recwarn.pop(DeprecationWarning)
+
+
 class TestWarningsRecorderChecker:
     def test_recording(self) -> None:
         rec = WarningsRecorder(_ispytest=True)