Move documentation contents from reference.rst to docstrings

It's better to have the documentation in one place, instead
of having some in the docstring and some additional
information added to the reference documentation in
`reference.rst`.

doc/en/reference/reference.rst

@@ -363,17 +363,6 @@ capsys
 .. autofunction:: _pytest.capture.capsys()
     :no-auto-options:
 
-    Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.
-
-    Example:
-
-    .. code-block:: python
-
-        def test_output(capsys):
-            print("hello")
-            captured = capsys.readouterr()
-            assert captured.out == "hello\n"
-
 .. autoclass:: pytest.CaptureFixture()
     :members:
 
@@ -388,18 +377,6 @@ capsysbinary
 .. autofunction:: _pytest.capture.capsysbinary()
     :no-auto-options:
 
-    Returns an instance of :class:`CaptureFixture[bytes] <pytest.CaptureFixture>`.
-
-    Example:
-
-    .. code-block:: python
-
-        def test_output(capsysbinary):
-            print("hello")
-            captured = capsysbinary.readouterr()
-            assert captured.out == b"hello\n"
-
-
 .. fixture:: capfd
 
 capfd
@@ -410,18 +387,6 @@ capfd
 .. autofunction:: _pytest.capture.capfd()
     :no-auto-options:
 
-    Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.
-
-    Example:
-
-    .. code-block:: python
-
-        def test_system_echo(capfd):
-            os.system('echo "hello"')
-            captured = capfd.readouterr()
-            assert captured.out == "hello\n"
-
-
 .. fixture:: capfdbinary
 
 capfdbinary
@@ -432,17 +397,6 @@ capfdbinary
 .. autofunction:: _pytest.capture.capfdbinary()
     :no-auto-options:
 
-    Returns an instance of :class:`CaptureFixture[bytes] <pytest.CaptureFixture>`.
-
-    Example:
-
-    .. code-block:: python
-
-        def test_system_echo(capfdbinary):
-            os.system('echo "hello"')
-            captured = capfdbinary.readouterr()
-            assert captured.out == b"hello\n"
-
 
 .. fixture:: doctest_namespace
 
@@ -453,16 +407,6 @@ doctest_namespace
 
 .. autofunction:: _pytest.doctest.doctest_namespace()
 
-    Usually this fixture is used in conjunction with another ``autouse`` fixture:
-
-    .. code-block:: python
-
-        @pytest.fixture(autouse=True)
-        def add_np(doctest_namespace):
-            doctest_namespace["np"] = numpy
-
-    For more details: :ref:`doctest_namespace`.
-
 
 .. fixture:: request
 
@@ -600,12 +544,6 @@ recwarn
 .. autoclass:: pytest.WarningsRecorder()
     :members:
 
-Each recorded warning is an instance of :class:`warnings.WarningMessage`.
-
-.. note::
-    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
-    differently; see :ref:`ensuring_function_triggers`.
-
 
 .. fixture:: tmp_path
 

src/_pytest/capture.py

@@ -876,11 +876,22 @@ class CaptureFixture(Generic[AnyStr]):
 
 @fixture
 def capsys(request: SubRequest) -> Generator[CaptureFixture[str], None, None]:
-    """Enable text capturing of writes to ``sys.stdout`` and ``sys.stderr``.
+    r"""Enable text capturing of writes to ``sys.stdout`` and ``sys.stderr``.
 
     The captured output is made available via ``capsys.readouterr()`` method
     calls, which return a ``(out, err)`` namedtuple.
     ``out`` and ``err`` will be ``text`` objects.
+
+    Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_output(capsys):
+            print("hello")
+            captured = capsys.readouterr()
+            assert captured.out == "hello\n"
     """
     capman = request.config.pluginmanager.getplugin("capturemanager")
     capture_fixture = CaptureFixture[str](SysCapture, request, _ispytest=True)
@@ -893,11 +904,22 @@ def capsys(request: SubRequest) -> Generator[CaptureFixture[str], None, None]:
 
 @fixture
 def capsysbinary(request: SubRequest) -> Generator[CaptureFixture[bytes], None, None]:
-    """Enable bytes capturing of writes to ``sys.stdout`` and ``sys.stderr``.
+    r"""Enable bytes capturing of writes to ``sys.stdout`` and ``sys.stderr``.
 
     The captured output is made available via ``capsysbinary.readouterr()``
     method calls, which return a ``(out, err)`` namedtuple.
     ``out`` and ``err`` will be ``bytes`` objects.
+
+    Returns an instance of :class:`CaptureFixture[bytes] <pytest.CaptureFixture>`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_output(capsysbinary):
+            print("hello")
+            captured = capsysbinary.readouterr()
+            assert captured.out == b"hello\n"
     """
     capman = request.config.pluginmanager.getplugin("capturemanager")
     capture_fixture = CaptureFixture[bytes](SysCaptureBinary, request, _ispytest=True)
@@ -910,11 +932,22 @@ def capsysbinary(request: SubRequest) -> Generator[CaptureFixture[bytes], None,
 
 @fixture
 def capfd(request: SubRequest) -> Generator[CaptureFixture[str], None, None]:
-    """Enable text capturing of writes to file descriptors ``1`` and ``2``.
+    r"""Enable text capturing of writes to file descriptors ``1`` and ``2``.
 
     The captured output is made available via ``capfd.readouterr()`` method
     calls, which return a ``(out, err)`` namedtuple.
     ``out`` and ``err`` will be ``text`` objects.
+
+    Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_system_echo(capfd):
+            os.system('echo "hello"')
+            captured = capfd.readouterr()
+            assert captured.out == "hello\n"
     """
     capman = request.config.pluginmanager.getplugin("capturemanager")
     capture_fixture = CaptureFixture[str](FDCapture, request, _ispytest=True)
@@ -927,11 +960,23 @@ def capfd(request: SubRequest) -> Generator[CaptureFixture[str], None, None]:
 
 @fixture
 def capfdbinary(request: SubRequest) -> Generator[CaptureFixture[bytes], None, None]:
-    """Enable bytes capturing of writes to file descriptors ``1`` and ``2``.
+    r"""Enable bytes capturing of writes to file descriptors ``1`` and ``2``.
 
     The captured output is made available via ``capfd.readouterr()`` method
     calls, which return a ``(out, err)`` namedtuple.
     ``out`` and ``err`` will be ``byte`` objects.
+
+    Returns an instance of :class:`CaptureFixture[bytes] <pytest.CaptureFixture>`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_system_echo(capfdbinary):
+            os.system('echo "hello"')
+            captured = capfdbinary.readouterr()
+            assert captured.out == b"hello\n"
+
     """
     capman = request.config.pluginmanager.getplugin("capturemanager")
     capture_fixture = CaptureFixture[bytes](FDCaptureBinary, request, _ispytest=True)

src/_pytest/doctest.py

@@ -730,5 +730,16 @@ def _get_report_choice(key: str) -> int:
 @pytest.fixture(scope="session")
 def doctest_namespace() -> Dict[str, Any]:
     """Fixture that returns a :py:class:`dict` that will be injected into the
-    namespace of doctests."""
+    namespace of doctests.
+
+    Usually this fixture is used in conjunction with another ``autouse`` fixture:
+
+    .. code-block:: python
+
+        @pytest.fixture(autouse=True)
+        def add_np(doctest_namespace):
+            doctest_namespace["np"] = numpy
+
+    For more details: :ref:`doctest_namespace`.
+    """
     return dict()

src/_pytest/recwarn.py

@@ -160,7 +160,14 @@ def warns(
 class WarningsRecorder(warnings.catch_warnings):
     """A context manager to record raised warnings.
 
+    Each recorded warning is an instance of :class:`warnings.WarningMessage`.
+
     Adapted from `warnings.catch_warnings`.
+
+    .. note::
+        ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
+        differently; see :ref:`ensuring_function_triggers`.
+
     """
 
     def __init__(self, *, _ispytest: bool = False) -> None: