Improving sphinx docs based on feedback

Author: arel

doc/en/example/parametrize.rst

@@ -560,11 +560,13 @@ As the result:
 - The test ``test_eval[basic_2+4]`` passed.
 - The test ``test_eval[basic_6*9]`` was expected to fail and did fail.
 
-Parametrizing conditional raising with ``pytest.raises``
+.. _`parametrizing_conditional_raising`:
+
+Parametrizing conditional raising
 --------------------------------------------------------------------
 
-Use ``pytest.raises`` and ``pytest.does_not_raise`` together with the
-``parametrize`` decorator to write parametrized tests in which some
+Use :func:`pytest.raises` and :func:`pytest.does_not_raise` together with the
+:ref:`pytest.mark.parametrize ref` decorator to write parametrized tests in which some
 tests raise exceptions and others do not. For example::
 
     import pytest
@@ -580,5 +582,5 @@ tests raise exceptions and others do not. For example::
         with expectation:
             assert (6 / example_input) is not None
 
-In this example, the first three tests should run unexceptionally,
-while the fourth test should raise ``ZeroDivisionError``.
+In this example, the first three test cases should run unexceptionally,
+while the fourth should raise ``ZeroDivisionError``.

doc/en/reference.rst

@@ -61,6 +61,12 @@ pytest.raises
 .. autofunction:: pytest.raises(expected_exception: Exception, [match], [message])
     :with: excinfo
 
+pytest.does_not_raise
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: pytest.does_not_raise()
+    :with: excinfo
+
 pytest.deprecated_call
 ~~~~~~~~~~~~~~~~~~~~~~
 

src/_pytest/python_api.py

@@ -622,6 +622,14 @@ def raises(expected_exception, *args, **kwargs):
            ...
            >>> assert exc_info.type is ValueError
 
+    **Using with** ``pytest.mark.parametrize``
+
+    When using :ref:`pytest.mark.parametrize ref`
+    it is possible to parametrize tests such that
+    some runs raise an exception and others do not.
+
+    See :ref:`parametrizing_conditional_raising` for an example.
+
     **Legacy form**
 
     It is possible to specify a callable by passing a to-be-called lambda::
@@ -734,13 +742,13 @@ def __exit__(self, *tp):
 
 @contextmanager
 def does_not_raise():
-    r"""
+    r'''
     This context manager is a complement to ``pytest.raises()`` that does
     *not* catch any exceptions raised by the code block.
 
 
-    This is essentially a no-op but is useful when
-    conditionally parameterizing tests that may or may not
+    This is essentially a *no-op* but is useful when
+    conditionally parametrizing tests that may or may not
     raise an error. For example::
 
         @pytest.mark.parametrize('example_input,expectation', [
@@ -750,9 +758,14 @@ def does_not_raise():
             (0, raises(ZeroDivisionError)),
         ])
         def test_division(example_input, expectation):
-            '''Test how much I know division.'''
-            with expectation:
+            """Test how much I know division."""
+            with expectation as excinfo:
                 assert (6 / example_input) is not None
-    """
+
+    Note that `excinfo` will be *None* when using
+    ``does_not_raise``. In the example above, `execinfo`
+    will be `None` for the first three runs and
+    an :class:`ExceptionInfo` instance on last run.
+    '''
 
     yield

testing/python/raises.py

@@ -98,7 +98,6 @@ def test_does_not_raise(self, testdir):
         testdir.makepyfile(
             """
             import pytest
-            import _pytest._code
 
             @pytest.mark.parametrize('example_input,expectation', [
                 (3, pytest.does_not_raise()),
@@ -119,7 +118,6 @@ def test_does_not_raise_does_raise(self, testdir):
         testdir.makepyfile(
             """
             import pytest
-            import _pytest._code
 
             @pytest.mark.parametrize('example_input,expectation', [
                 (0, pytest.does_not_raise()),