Add reference docs to cache and capture fixtures

_pytest/capture.py

@@ -197,9 +197,9 @@ def _ensure_only_one_capture_fixture(request, name):
 
 @pytest.fixture
 def capsys(request):
-    """Enable capturing of writes to sys.stdout/sys.stderr and make
+    """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make
     captured output available via ``capsys.readouterr()`` method calls
-    which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``text``
+    which return a ``(out, err)`` namedtuple.  ``out`` and ``err`` will be ``text``
     objects.
     """
     _ensure_only_one_capture_fixture(request, 'capsys')
@@ -209,7 +209,7 @@ def capsys(request):
 
 @pytest.fixture
 def capsysbinary(request):
-    """Enable capturing of writes to sys.stdout/sys.stderr and make
+    """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make
     captured output available via ``capsys.readouterr()`` method calls
     which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``bytes``
     objects.
@@ -225,7 +225,7 @@ def capsysbinary(request):
 
 @pytest.fixture
 def capfd(request):
-    """Enable capturing of writes to file descriptors 1 and 2 and make
+    """Enable capturing of writes to file descriptors ``1`` and ``2`` and make
     captured output available via ``capfd.readouterr()`` method calls
     which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``text``
     objects.
@@ -272,6 +272,10 @@ def _install_capture_fixture_on_item(request, capture_class):
 
 
 class CaptureFixture(object):
+    """
+    Object returned by :py:func:`capsys`, :py:func:`capsysbinary`, :py:func:`capfd` and :py:func:`capfdbinary`
+    fixtures.
+    """
     def __init__(self, captureclass, request):
         self.captureclass = captureclass
         self.request = request
@@ -288,6 +292,11 @@ class CaptureFixture(object):
             cap.stop_capturing()
 
     def readouterr(self):
+        """Read and return the captured output so far.
+
+        :rtype: Tuple[str, str]
+        :return: captured content as a pair of (stdout, stdout) strings
+        """
         try:
             return self._capture.readouterr()
         except AttributeError:
@@ -295,6 +304,7 @@ class CaptureFixture(object):
 
     @contextlib.contextmanager
     def disabled(self):
+        """Temporarily disables capture while inside the 'with' block."""
         self._capture.suspend_capturing()
         capmanager = self.request.config.pluginmanager.getplugin('capturemanager')
         capmanager.suspend_global_capture(item=None, in_=False)

_pytest/fixtures.py

@@ -858,7 +858,7 @@ class FixtureFunctionMarker(object):
 
 
 def fixture(scope="function", params=None, autouse=False, ids=None, name=None):
-    """ (return a) decorator to mark a fixture factory function.
+    """Decorator to mark a fixture factory function.
 
     This decorator can be used (with or without parameters) to define a
     fixture function.  The name of the fixture function can later be

doc/en/cache.rst

@@ -212,7 +212,7 @@ the cache and this will be quick::
     test_caching.py:14: AssertionError
     1 failed in 0.12 seconds
 
-See the `cache-api`_ for more details.
+See the :ref:`cache-api` for more details.
 
 
 Inspecting Cache content
@@ -247,22 +247,3 @@ servers where isolation and correctness is more important
 than speed.
 
 
-.. _`cache-api`:
-
-config.cache API
-------------------
-
-The ``config.cache`` object allows other plugins,
-including ``conftest.py`` files,
-to safely and flexibly store and retrieve values across
-test runs because the ``config`` object is available
-in many places.
-
-Under the hood, the cache plugin uses the simple
-dumps/loads API of the json stdlib module
-
-.. currentmodule:: _pytest.cacheprovider
-
-.. automethod:: Cache.get
-.. automethod:: Cache.set
-.. automethod:: Cache.makedir

doc/en/reference.rst

@@ -118,7 +118,6 @@ reporting or interaction with exceptions:
 .. autofunction:: pytest_enter_pdb
 
 
-
 Objects
 -------
 
@@ -196,3 +195,140 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 .. autoclass:: LineMatcher()
     :members:
 
+.. autoclass:: _pytest.capture.CaptureFixture()
+    :members:
+
+
+Fixtures
+--------
+
+Fixtures are requested by test functions or other fixtures by declaring them as argument names.
+
+
+Example of a test requiring a fixture:
+
+.. code-block:: python
+
+    def test_output(capsys):
+        print('hello')
+        out, err = capsys.readouterr()
+        assert out == 'hello\n'
+
+
+Example of a fixture requiring another fixture:
+
+.. code-block:: python
+
+    @pytest.fixture
+    def db_session(tmpdir):
+        fn = tmpdir / 'db.file'
+        return connect(str(fn))
+
+For more details, consult the full :ref:`fixtures docs <fixture>`.
+
+
+fixture decorator signature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: _pytest.fixtures
+.. autofunction:: fixture
+    :decorator:
+
+
+.. _`cache-api`:
+
+config.cache
+~~~~~~~~~~~~
+
+The ``config.cache`` object allows other plugins and fixtures
+to store and retrieve values across test runs. To access it from fixtures
+request ``pytestconfig`` into your fixture and get it with ``pytestconfig.cache``.
+
+Under the hood, the cache plugin uses the simple
+``dumps``/``loads`` API of the :py:mod:`json` stdlib module.
+
+.. currentmodule:: _pytest.cacheprovider
+
+.. automethod:: Cache.get
+.. automethod:: Cache.set
+.. automethod:: Cache.makedir
+
+
+capsys
+~~~~~~
+
+.. currentmodule:: _pytest.capture
+
+.. autofunction:: capsys()
+    :no-auto-options:
+    :decorator:
+
+    Returns an instance of :py:class:`CaptureFixture`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_output(capsys):
+            print("hello")
+            captured = capsys.readouterr()
+            assert captured.out == "hello\n"
+
+
+capsysbinary
+~~~~~~~~~~~~
+
+.. autofunction:: capsysbinary()
+    :no-auto-options:
+    :decorator:
+
+    Returns an instance of :py:class:`CaptureFixture`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_output(capsysbinary):
+            print("hello")
+            captured = capsysbinary.readouterr()
+            assert captured.out == b"hello\n"
+
+
+capfd
+~~~~~~
+
+.. autofunction:: capfd()
+    :no-auto-options:
+    :decorator:
+
+    Returns an instance of :py:class:`CaptureFixture`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_system_echo(capfd):
+            os.system('echo "hello"')
+            captured = capsys.readouterr()
+            assert captured.out == "hello\n"
+
+
+capfdbinary
+~~~~~~~~~~~~
+
+.. autofunction:: capfdbinary()
+    :no-auto-options:
+    :decorator:
+
+    Returns an instance of :py:class:`CaptureFixture`.
+
+    Example:
+
+    .. code-block:: python
+
+        def test_system_echo(capfdbinary):
+            os.system('echo "hello"')
+            captured = capfdbinary.readouterr()
+            assert captured.out == b"hello\n"
+
+