From e42fe5f0f93f2f5849c26360971ff9eb900c69c3 Mon Sep 17 00:00:00 2001
From: Jeffrey Rackauckas <jeffreyrack@gmail.com>
Date: Mon, 5 Mar 2018 19:35:41 -0800
Subject: [PATCH 01/51] Add doc to norecursedirs in tox.ini

---
 changelog/3245.trivial.rst | 1 +
 tox.ini                    | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelog/3245.trivial.rst

diff --git a/changelog/3245.trivial.rst b/changelog/3245.trivial.rst
new file mode 100644
index 000000000..b61d9804f
--- /dev/null
+++ b/changelog/3245.trivial.rst
@@ -0,0 +1 @@
+Added ``doc`` to norecursedirs in tox.ini
\ No newline at end of file
diff --git a/tox.ini b/tox.ini
index b90bd432d..12e7a57fb 100644
--- a/tox.ini
+++ b/tox.ini
@@ -204,7 +204,7 @@ rsyncdirs = tox.ini pytest.py _pytest testing
 python_files = test_*.py *_test.py testing/*/*.py
 python_classes = Test Acceptance
 python_functions = test
-norecursedirs = .tox ja .hg cx_freeze_source
+norecursedirs = .tox ja .hg cx_freeze_source doc
 xfail_strict=true
 filterwarnings =
     error

From d4c38502312ee13991d05dfc5709f825a77ed6a7 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 7 Feb 2018 20:53:31 -0200
Subject: [PATCH 02/51] Create reference and moved Objects and Hooks reference
 from writing_plugins

---
 doc/en/_templates/globaltoc.html |   3 +-
 doc/en/contents.rst              |   1 +
 doc/en/reference.rst             | 198 +++++++++++++++++++++++++++++++
 doc/en/writing_plugins.rst       | 194 +-----------------------------
 4 files changed, 206 insertions(+), 190 deletions(-)
 create mode 100644 doc/en/reference.rst

diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html
index fdd4dd59b..8f346fa89 100644
--- a/doc/en/_templates/globaltoc.html
+++ b/doc/en/_templates/globaltoc.html
@@ -2,8 +2,9 @@
 
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
-  <li><a href="{{ pathto('contents') }}">Contents</a></li>
   <li><a href="{{ pathto('getting-started') }}">Install</a></li>
+  <li><a href="{{ pathto('contents') }}">Contents</a></li>
+  <li><a href="{{ pathto('reference') }}">Reference</a></li>
   <li><a href="{{ pathto('example/index') }}">Examples</a></li>
   <li><a href="{{ pathto('customize') }}">Customize</a></li>
   <li><a href="{{ pathto('contact') }}">Contact</a></li>
diff --git a/doc/en/contents.rst b/doc/en/contents.rst
index 7a6570e0b..b98d0a17c 100644
--- a/doc/en/contents.rst
+++ b/doc/en/contents.rst
@@ -31,6 +31,7 @@ Full pytest documentation
    plugins
    writing_plugins
    logging
+   reference
 
    goodpractices
    pythonpath
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
new file mode 100644
index 000000000..20c0549fc
--- /dev/null
+++ b/doc/en/reference.rst
@@ -0,0 +1,198 @@
+
+Reference
+=========
+
+This page contains the full reference to pytest's API.
+
+
+.. _`hook-reference`:
+
+Hooks
+-----
+
+
+.. currentmodule:: _pytest.hookspec
+
+Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
+
+Bootstrapping hooks
+~~~~~~~~~~~~~~~~~~~
+
+Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
+
+.. autofunction:: pytest_load_initial_conftests
+.. autofunction:: pytest_cmdline_preparse
+.. autofunction:: pytest_cmdline_parse
+.. autofunction:: pytest_cmdline_main
+
+Initialization hooks
+~~~~~~~~~~~~~~~~~~~~
+
+Initialization hooks called for plugins and ``conftest.py`` files.
+
+.. autofunction:: pytest_addoption
+.. autofunction:: pytest_configure
+.. autofunction:: pytest_unconfigure
+
+Test running hooks
+~~~~~~~~~~~~~~~~~~
+
+All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
+
+.. autofunction:: pytest_runtestloop
+.. autofunction:: pytest_runtest_protocol
+.. autofunction:: pytest_runtest_logstart
+.. autofunction:: pytest_runtest_logfinish
+.. autofunction:: pytest_runtest_setup
+.. autofunction:: pytest_runtest_call
+.. autofunction:: pytest_runtest_teardown
+.. autofunction:: pytest_runtest_makereport
+
+For deeper understanding you may look at the default implementation of
+these hooks in :py:mod:`_pytest.runner` and maybe also
+in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
+and its input/output capturing in order to immediately drop
+into interactive debugging when a test failure occurs.
+
+The :py:mod:`_pytest.terminal` reported specifically uses
+the reporting hook to print information about a test run.
+
+Collection hooks
+~~~~~~~~~~~~~~~~
+
+``pytest`` calls the following hooks for collecting files and directories:
+
+.. autofunction:: pytest_collection
+.. autofunction:: pytest_ignore_collect
+.. autofunction:: pytest_collect_directory
+.. autofunction:: pytest_collect_file
+
+For influencing the collection of objects in Python modules
+you can use the following hook:
+
+.. autofunction:: pytest_pycollect_makeitem
+.. autofunction:: pytest_generate_tests
+.. autofunction:: pytest_make_parametrize_id
+
+After collection is complete, you can modify the order of
+items, delete or otherwise amend the test items:
+
+.. autofunction:: pytest_collection_modifyitems
+
+Reporting hooks
+~~~~~~~~~~~~~~~
+
+Session related reporting hooks:
+
+.. autofunction:: pytest_collectstart
+.. autofunction:: pytest_itemcollected
+.. autofunction:: pytest_collectreport
+.. autofunction:: pytest_deselected
+.. autofunction:: pytest_report_header
+.. autofunction:: pytest_report_collectionfinish
+.. autofunction:: pytest_report_teststatus
+.. autofunction:: pytest_terminal_summary
+.. autofunction:: pytest_fixture_setup
+.. autofunction:: pytest_fixture_post_finalizer
+
+And here is the central hook for reporting about
+test execution:
+
+.. autofunction:: pytest_runtest_logreport
+
+You can also use this hook to customize assertion representation for some
+types:
+
+.. autofunction:: pytest_assertrepr_compare
+
+
+Debugging/Interaction hooks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are few hooks which can be used for special
+reporting or interaction with exceptions:
+
+.. autofunction:: pytest_internalerror
+.. autofunction:: pytest_keyboard_interrupt
+.. autofunction:: pytest_exception_interact
+.. autofunction:: pytest_enter_pdb
+
+
+
+Objects
+-------
+
+Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
+
+.. autoclass:: _pytest.config.Config()
+    :members:
+
+.. autoclass:: _pytest.config.Parser()
+    :members:
+
+.. autoclass:: _pytest.nodes.Node()
+    :members:
+
+.. autoclass:: _pytest.nodes.Collector()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.nodes.FSCollector()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.main.Session()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.nodes.Item()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.python.Module()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.python.Class()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.python.Function()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.fixtures.FixtureDef()
+    :members:
+    :show-inheritance:
+
+.. autoclass:: _pytest.runner.CallInfo()
+    :members:
+
+.. autoclass:: _pytest.runner.TestReport()
+    :members:
+    :inherited-members:
+
+.. autoclass:: pluggy._Result
+    :members:
+
+.. autofunction:: _pytest.config.get_plugin_manager()
+
+.. autoclass:: _pytest.config.PytestPluginManager()
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pluggy.PluginManager()
+    :members:
+
+.. currentmodule:: _pytest.pytester
+
+.. autoclass:: Testdir()
+    :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
+
+.. autoclass:: RunResult()
+    :members:
+
+.. autoclass:: LineMatcher()
+    :members:
+
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index d88bb8f15..55f692a6a 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -12,9 +12,9 @@ only want to use but not write plugins.
 A plugin contains one or multiple hook functions. :ref:`Writing hooks <writinghooks>`
 explains the basics and details of how you can write a hook function yourself.
 ``pytest`` implements all aspects of configuration, collection, running and
-reporting by calling `well specified hooks`_ of the following plugins:
+reporting by calling :ref:`well specified hooks <hook-reference>` of the following plugins:
 
-* :ref:`builtin plugins`: loaded from pytest's internal ``_pytest`` directory.
+* builtin plugins: loaded from pytest's internal ``_pytest`` directory.
 
 * :ref:`external plugins <extplugins>`: modules discovered through
   `setuptools entry points`_
@@ -109,10 +109,10 @@ If you want to write a plugin, there are many real-life examples
 you can copy from:
 
 * a custom collection example plugin: :ref:`yaml plugin`
-* around 20 :ref:`builtin plugins` which provide pytest's own functionality
+* builtin plugins which provide pytest's own functionality
 * many `external plugins <http://plugincompat.herokuapp.com>`_ providing additional features
 
-All of these plugins implement the documented `well specified hooks`_
+All of these plugins implement :ref:`hooks <hook-reference>` and/or :ref:`fixtures <fixture>`
 to extend and add functionality.
 
 .. note::
@@ -167,7 +167,7 @@ it in your setuptools-invocation:
 
 If a package is installed this way, ``pytest`` will load
 ``myproject.pluginmodule`` as a plugin which can define
-`well specified hooks`_.
+:ref:`hooks <hook-reference>`.
 
 .. note::
 
@@ -577,191 +577,7 @@ declaring the hook functions directly in your plugin module, for example::
 This has the added benefit of allowing you to conditionally install hooks
 depending on which plugins are installed.
 
-.. _`well specified hooks`:
-
-.. currentmodule:: _pytest.hookspec
-
-pytest hook reference
-=====================
 
 
-Initialization, command line and configuration hooks
-----------------------------------------------------
-
-Bootstrapping hooks
-~~~~~~~~~~~~~~~~~~~
-
-Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
-
-.. autofunction:: pytest_load_initial_conftests
-.. autofunction:: pytest_cmdline_preparse
-.. autofunction:: pytest_cmdline_parse
-.. autofunction:: pytest_cmdline_main
-
-Initialization hooks
-~~~~~~~~~~~~~~~~~~~~
-
-Initialization hooks called for plugins and ``conftest.py`` files.
-
-.. autofunction:: pytest_addoption
-.. autofunction:: pytest_configure
-.. autofunction:: pytest_unconfigure
-
-Generic "runtest" hooks
------------------------
-
-All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
-
-.. autofunction:: pytest_runtestloop
-.. autofunction:: pytest_runtest_protocol
-.. autofunction:: pytest_runtest_logstart
-.. autofunction:: pytest_runtest_logfinish
-.. autofunction:: pytest_runtest_setup
-.. autofunction:: pytest_runtest_call
-.. autofunction:: pytest_runtest_teardown
-.. autofunction:: pytest_runtest_makereport
-
-For deeper understanding you may look at the default implementation of
-these hooks in :py:mod:`_pytest.runner` and maybe also
-in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
-and its input/output capturing in order to immediately drop
-into interactive debugging when a test failure occurs.
-
-The :py:mod:`_pytest.terminal` reported specifically uses
-the reporting hook to print information about a test run.
-
-Collection hooks
-----------------
-
-``pytest`` calls the following hooks for collecting files and directories:
-
-.. autofunction:: pytest_collection
-.. autofunction:: pytest_ignore_collect
-.. autofunction:: pytest_collect_directory
-.. autofunction:: pytest_collect_file
-
-For influencing the collection of objects in Python modules
-you can use the following hook:
-
-.. autofunction:: pytest_pycollect_makeitem
-.. autofunction:: pytest_generate_tests
-.. autofunction:: pytest_make_parametrize_id
-
-After collection is complete, you can modify the order of
-items, delete or otherwise amend the test items:
-
-.. autofunction:: pytest_collection_modifyitems
-
-Reporting hooks
----------------
-
-Session related reporting hooks:
-
-.. autofunction:: pytest_collectstart
-.. autofunction:: pytest_itemcollected
-.. autofunction:: pytest_collectreport
-.. autofunction:: pytest_deselected
-.. autofunction:: pytest_report_header
-.. autofunction:: pytest_report_collectionfinish
-.. autofunction:: pytest_report_teststatus
-.. autofunction:: pytest_terminal_summary
-.. autofunction:: pytest_fixture_setup
-.. autofunction:: pytest_fixture_post_finalizer
-
-And here is the central hook for reporting about
-test execution:
-
-.. autofunction:: pytest_runtest_logreport
-
-You can also use this hook to customize assertion representation for some
-types:
-
-.. autofunction:: pytest_assertrepr_compare
 
 
-Debugging/Interaction hooks
----------------------------
-
-There are few hooks which can be used for special
-reporting or interaction with exceptions:
-
-.. autofunction:: pytest_internalerror
-.. autofunction:: pytest_keyboard_interrupt
-.. autofunction:: pytest_exception_interact
-.. autofunction:: pytest_enter_pdb
-
-
-Reference of objects involved in hooks
-======================================
-
-.. autoclass:: _pytest.config.Config()
-    :members:
-
-.. autoclass:: _pytest.config.Parser()
-    :members:
-
-.. autoclass:: _pytest.nodes.Node()
-    :members:
-
-.. autoclass:: _pytest.nodes.Collector()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.nodes.FSCollector()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.main.Session()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.nodes.Item()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.python.Module()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.python.Class()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.python.Function()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.fixtures.FixtureDef()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.runner.CallInfo()
-    :members:
-
-.. autoclass:: _pytest.runner.TestReport()
-    :members:
-    :inherited-members:
-
-.. autoclass:: pluggy._Result
-    :members:
-
-.. autofunction:: _pytest.config.get_plugin_manager()
-
-.. autoclass:: _pytest.config.PytestPluginManager()
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. autoclass:: pluggy.PluginManager()
-    :members:
-
-.. currentmodule:: _pytest.pytester
-
-.. autoclass:: Testdir()
-    :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
-
-.. autoclass:: RunResult()
-    :members:
-
-.. autoclass:: LineMatcher()
-    :members:

From 162557c2b2ba97284fad2831cc8426df0feb6c93 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 7 Feb 2018 20:54:00 -0200
Subject: [PATCH 03/51] Remove internal plugin list

This gets out of sync and shows internal plugins which don't make
much sense
---
 doc/en/plugins.rst | 33 ---------------------------------
 1 file changed, 33 deletions(-)

diff --git a/doc/en/plugins.rst b/doc/en/plugins.rst
index 2a9fff81b..276b394d0 100644
--- a/doc/en/plugins.rst
+++ b/doc/en/plugins.rst
@@ -120,36 +120,3 @@ CI server), you can set ``PYTEST_ADDOPTS`` environment variable to
 See :ref:`findpluginname` for how to obtain the name of a plugin.
 
 .. _`builtin plugins`:
-
-Pytest default plugin reference
--------------------------------
-
-
-You can find the source code for the following plugins
-in the `pytest repository <https://github.com/pytest-dev/pytest>`_.
-
-.. autosummary::
-
-    _pytest.assertion
-    _pytest.cacheprovider
-    _pytest.capture
-    _pytest.config
-    _pytest.doctest
-    _pytest.helpconfig
-    _pytest.junitxml
-    _pytest.mark
-    _pytest.monkeypatch
-    _pytest.nose
-    _pytest.pastebin
-    _pytest.debugging
-    _pytest.pytester
-    _pytest.python
-    _pytest.recwarn
-    _pytest.resultlog
-    _pytest.runner
-    _pytest.main
-    _pytest.logging
-    _pytest.skipping
-    _pytest.terminal
-    _pytest.tmpdir
-    _pytest.unittest

From 6d4e72e1eb5b1331cc43f12255186eabdd9227a0 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 7 Feb 2018 21:00:10 -0200
Subject: [PATCH 04/51] Cleanup the links section to only external links

Internal links should be displayed in the side-bar
---
 doc/en/_templates/links.html | 2 --
 1 file changed, 2 deletions(-)

diff --git a/doc/en/_templates/links.html b/doc/en/_templates/links.html
index d855a013f..91157dfb7 100644
--- a/doc/en/_templates/links.html
+++ b/doc/en/_templates/links.html
@@ -1,7 +1,5 @@
 <h3>Useful Links</h3>
 <ul>
-  <li><a href="{{ pathto('index') }}">The pytest Website</a></li>
-  <li><a href="{{ pathto('contributing') }}">Contribution Guide</a></li>
   <li><a href="https://pypi.python.org/pypi/pytest">pytest @ PyPI</a></li>
   <li><a href="https://github.com/pytest-dev/pytest/">pytest @ GitHub</a></li>
   <li><a href="http://plugincompat.herokuapp.com/">3rd party plugins</a></li>

From 6b4565f8d19a67864f3651025b5189e45985bc5f Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 7 Feb 2018 21:00:31 -0200
Subject: [PATCH 05/51] Reorder the global toc and include 'contributing'
 section

---
 doc/en/_templates/globaltoc.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/en/_templates/globaltoc.html b/doc/en/_templates/globaltoc.html
index 8f346fa89..0e088d67e 100644
--- a/doc/en/_templates/globaltoc.html
+++ b/doc/en/_templates/globaltoc.html
@@ -7,11 +7,11 @@
   <li><a href="{{ pathto('reference') }}">Reference</a></li>
   <li><a href="{{ pathto('example/index') }}">Examples</a></li>
   <li><a href="{{ pathto('customize') }}">Customize</a></li>
-  <li><a href="{{ pathto('contact') }}">Contact</a></li>
-  <li><a href="{{ pathto('talks') }}">Talks/Posts</a></li>
   <li><a href="{{ pathto('changelog') }}">Changelog</a></li>
+  <li><a href="{{ pathto('contributing') }}">Contributing</a></li>
   <li><a href="{{ pathto('backwards-compatibility') }}">Backwards Compatibility</a></li>
   <li><a href="{{ pathto('license') }}">License</a></li>
+  <li><a href="{{ pathto('contact') }}">Contact Channels</a></li>
 </ul>
 
 {%- if display_toc %}

From 6fa9768545c69b2c17035b7a1282f243ac22532f Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 8 Feb 2018 18:54:20 -0200
Subject: [PATCH 06/51] Use sphinxcontrib-trio extension

This adds some more capabilities to sphinx, like marking
functions as decorators or with contexts
---
 doc/en/builtin.rst      |  2 ++
 doc/en/conf.py          | 11 ++++++-----
 doc/en/requirements.txt |  1 +
 tox.ini                 |  1 +
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst
index a380b9abd..5a4ea4b43 100644
--- a/doc/en/builtin.rst
+++ b/doc/en/builtin.rst
@@ -59,6 +59,8 @@ Fixtures and requests
 To mark a fixture function:
 
 .. autofunction:: _pytest.fixtures.fixture
+    :noindex:
+    :decorator:
 
 Tutorial at :ref:`fixtures`.
 
diff --git a/doc/en/conf.py b/doc/en/conf.py
index 40f1e4165..f5c17404b 100644
--- a/doc/en/conf.py
+++ b/doc/en/conf.py
@@ -18,8 +18,11 @@
 # The full version, including alpha/beta/rc tags.
 # The short X.Y version.
 
-import os, sys
+import os
+import sys
+
 from _pytest import __version__ as version
+
 release = ".".join(version.split(".")[:2])
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -38,7 +41,7 @@ todo_include_todos = 1
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.autosummary',
-    'sphinx.ext.intersphinx', 'sphinx.ext.viewcode']
+              'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'sphinxcontrib_trio']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -310,9 +313,7 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'python': ('http://docs.python.org/', None),
-#                       'lib': ("http://docs.python.org/2.7library/", None),
-                    }
+intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
 
 
 def setup(app):
diff --git a/doc/en/requirements.txt b/doc/en/requirements.txt
index 72bb60a81..e3cc47ed5 100644
--- a/doc/en/requirements.txt
+++ b/doc/en/requirements.txt
@@ -1,3 +1,4 @@
 # pinning sphinx to 1.4.* due to search issues with rtd:
 # https://github.com/rtfd/readthedocs-sphinx-ext/issues/25
 sphinx ==1.4.*
+sphinxcontrib-trio
diff --git a/tox.ini b/tox.ini
index 12e7a57fb..ecbe20af9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -129,6 +129,7 @@ basepython = python
 changedir = doc/en
 deps =
     sphinx
+    sphinxcontrib-trio
     attrs
     PyYAML
 

From 749288dcb62bb242ba454ec956ad2ce2ad93b54b Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 8 Feb 2018 19:57:26 -0200
Subject: [PATCH 07/51] Add reference docs to cache and capture fixtures

---
 _pytest/capture.py   |  18 ++++--
 _pytest/fixtures.py  |   2 +-
 doc/en/cache.rst     |  21 +------
 doc/en/reference.rst | 138 ++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 153 insertions(+), 26 deletions(-)

diff --git a/_pytest/capture.py b/_pytest/capture.py
index 36658acce..5171358ef 100644
--- a/_pytest/capture.py
+++ b/_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)
diff --git a/_pytest/fixtures.py b/_pytest/fixtures.py
index f9d0ef572..955a112b1 100644
--- a/_pytest/fixtures.py
+++ b/_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
diff --git a/doc/en/cache.rst b/doc/en/cache.rst
index e3423e95b..81ef38088 100644
--- a/doc/en/cache.rst
+++ b/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
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 20c0549fc..b10b3126c 100644
--- a/doc/en/reference.rst
+++ b/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"
+
+

From 70f93263e919dfb511e63b577d65cdddd965c517 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 8 Feb 2018 20:08:44 -0200
Subject: [PATCH 08/51] Add reference docs to doctest_namespace

---
 _pytest/doctest.py   |  2 +-
 doc/en/doctest.rst   |  2 ++
 doc/en/reference.rst | 22 ++++++++++++++--------
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/_pytest/doctest.py b/_pytest/doctest.py
index f54f833ec..a7bb2598c 100644
--- a/_pytest/doctest.py
+++ b/_pytest/doctest.py
@@ -379,6 +379,6 @@ def _fix_spoof_python2(runner, encoding):
 @pytest.fixture(scope='session')
 def doctest_namespace():
     """
-    Inject names into the doctest namespace.
+    Fixture that returns a :py:class:`dict` that will be injected into the namespace of doctests.
     """
     return dict()
diff --git a/doc/en/doctest.rst b/doc/en/doctest.rst
index 61fbe04d4..78255516a 100644
--- a/doc/en/doctest.rst
+++ b/doc/en/doctest.rst
@@ -116,6 +116,8 @@ itself::
     'Hello'
 
 
+.. _`doctest_namespace`:
+
 The 'doctest_namespace' fixture
 -------------------------------
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index b10b3126c..91a26e31c 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -260,8 +260,6 @@ capsys
 .. currentmodule:: _pytest.capture
 
 .. autofunction:: capsys()
-    :no-auto-options:
-    :decorator:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -279,8 +277,6 @@ capsysbinary
 ~~~~~~~~~~~~
 
 .. autofunction:: capsysbinary()
-    :no-auto-options:
-    :decorator:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -298,8 +294,6 @@ capfd
 ~~~~~~
 
 .. autofunction:: capfd()
-    :no-auto-options:
-    :decorator:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -317,8 +311,6 @@ capfdbinary
 ~~~~~~~~~~~~
 
 .. autofunction:: capfdbinary()
-    :no-auto-options:
-    :decorator:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -332,3 +324,17 @@ capfdbinary
             assert captured.out == b"hello\n"
 
 
+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`.

From 623bab4447e9ec9b109055c542121e4b4ea8b1f4 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 8 Feb 2018 20:29:04 -0200
Subject: [PATCH 09/51] Use :no-auto-options: in capsys fixtures

Otherwise they are recognized as iterators
---
 doc/en/reference.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 91a26e31c..a0126747c 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -260,6 +260,7 @@ capsys
 .. currentmodule:: _pytest.capture
 
 .. autofunction:: capsys()
+    :no-auto-options:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -277,6 +278,7 @@ capsysbinary
 ~~~~~~~~~~~~
 
 .. autofunction:: capsysbinary()
+    :no-auto-options:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -294,6 +296,7 @@ capfd
 ~~~~~~
 
 .. autofunction:: capfd()
+    :no-auto-options:
 
     Returns an instance of :py:class:`CaptureFixture`.
 
@@ -311,6 +314,7 @@ capfdbinary
 ~~~~~~~~~~~~
 
 .. autofunction:: capfdbinary()
+    :no-auto-options:
 
     Returns an instance of :py:class:`CaptureFixture`.
 

From e7bce90d2972324c34dc74eb226f845dfb371faa Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 26 Feb 2018 20:08:38 -0300
Subject: [PATCH 10/51] Remove basepython from testenv:docs so it can be built
 with Python 3

---
 tox.ini | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index ecbe20af9..b059d03af 100644
--- a/tox.ini
+++ b/tox.ini
@@ -125,7 +125,6 @@ deps =
 [testenv:docs]
 skipsdist = True
 usedevelop = True
-basepython = python
 changedir = doc/en
 deps =
     sphinx

From e73d4f4e1fb37cc59c559f181b25c030ab3ffa7b Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 26 Feb 2018 20:13:33 -0300
Subject: [PATCH 11/51] Add local table of contents in reference.rst

---
 doc/en/reference.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index a0126747c..de916d511 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -4,6 +4,10 @@ Reference
 
 This page contains the full reference to pytest's API.
 
+.. contents::
+    :depth: 2
+    :local: 
+
 
 .. _`hook-reference`:
 

From b53c4246effa99217d4e26a6c9f74e3dd9eae66b Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 26 Feb 2018 20:27:15 -0300
Subject: [PATCH 12/51] Move most of 'builtin' to 'reference'

---
 doc/en/builtin.rst         | 158 +++----------------------------------
 doc/en/contents.rst        |   1 -
 doc/en/getting-started.rst |   3 +-
 doc/en/reference.rst       |  35 +++++++-
 4 files changed, 43 insertions(+), 154 deletions(-)

diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst
index 5a4ea4b43..91cdb004b 100644
--- a/doc/en/builtin.rst
+++ b/doc/en/builtin.rst
@@ -1,167 +1,27 @@
+:orphan:
 
 .. _`pytest helpers`:
 
 Pytest API and builtin fixtures
 ================================================
 
-This is a list of ``pytest.*`` API functions and fixtures.
+
+Most of the information of this page has been moved over to :ref:`reference`.
 
 For information on plugin hooks and objects, see :ref:`plugins`.
 
 For information on the ``pytest.mark`` mechanism, see :ref:`mark`.
 
-For the below objects, you can also interactively ask for help, e.g. by
-typing on the Python interactive prompt something like::
+For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures, type::
+
+    $ pytest -q --fixtures
+
+
+You can also interactively ask for help, e.g. by typing on the Python interactive prompt something like::
 
     import pytest
     help(pytest)
 
-.. currentmodule:: pytest
-
-Invoking pytest interactively
----------------------------------------------------
-
-.. autofunction:: main
-
-More examples at :ref:`pytest.main-usage`
 
 
-Helpers for assertions about Exceptions/Warnings
---------------------------------------------------------
 
-.. autofunction:: raises
-
-Examples at :ref:`assertraises`.
-
-.. autofunction:: deprecated_call
-
-Comparing floating point numbers
---------------------------------
-
-.. autofunction:: approx
-
-Raising a specific test outcome
---------------------------------------
-
-You can use the following functions in your test, fixture or setup
-functions to force a certain test outcome.  Note that most often
-you can rather use declarative marks, see :ref:`skipping`.
-
-.. autofunction:: _pytest.outcomes.fail
-.. autofunction:: _pytest.outcomes.skip
-.. autofunction:: _pytest.outcomes.importorskip
-.. autofunction:: _pytest.outcomes.xfail
-.. autofunction:: _pytest.outcomes.exit
-
-Fixtures and requests
------------------------------------------------------
-
-To mark a fixture function:
-
-.. autofunction:: _pytest.fixtures.fixture
-    :noindex:
-    :decorator:
-
-Tutorial at :ref:`fixtures`.
-
-The ``request`` object that can be used from fixture functions.
-
-.. autoclass:: _pytest.fixtures.FixtureRequest()
-    :members:
-
-
-.. _builtinfixtures:
-.. _builtinfuncargs:
-
-Builtin fixtures/function arguments
------------------------------------------
-
-You can ask for available builtin or project-custom
-:ref:`fixtures <fixtures>` by typing::
-
-    $ pytest -q --fixtures
-    cache
-        Return a cache object that can persist state between testing sessions.
-        
-        cache.get(key, default)
-        cache.set(key, value)
-        
-        Keys must be a ``/`` separated value, where the first part is usually the
-        name of your plugin or application to avoid clashes with other cache users.
-        
-        Values can be any object handled by the json stdlib module.
-    capsys
-        Enable capturing of writes to sys.stdout/sys.stderr and make
-        captured output available via ``capsys.readouterr()`` method calls
-        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be ``text``
-        objects.
-    capsysbinary
-        Enable capturing of writes to sys.stdout/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.
-    capfd
-        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.
-    capfdbinary
-        Enable capturing of write to file descriptors 1 and 2 and make
-        captured output available via ``capfdbinary.readouterr`` method calls
-        which return a ``(out, err)`` tuple.  ``out`` and ``err`` will be
-        ``bytes`` objects.
-    doctest_namespace
-        Inject names into the doctest namespace.
-    pytestconfig
-        the pytest config object with access to command line opts.
-    record_xml_property
-        Add extra xml properties to the tag for the calling test.
-        The fixture is callable with ``(name, value)``, with value being automatically
-        xml-encoded.
-    record_xml_attribute
-        Add extra xml attributes to the tag for the calling test.
-        The fixture is callable with ``(name, value)``, with value being automatically
-        xml-encoded
-    caplog
-        Access and control log capturing.
-        
-        Captured logs are available through the following methods::
-        
-        * caplog.text()          -> string containing formatted log output
-        * caplog.records()       -> list of logging.LogRecord instances
-        * caplog.record_tuples() -> list of (logger_name, level, message) tuples
-    monkeypatch
-        The returned ``monkeypatch`` fixture provides these
-        helper methods to modify objects, dictionaries or 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=False)
-            monkeypatch.delenv(name, value, raising=True)
-            monkeypatch.syspath_prepend(path)
-            monkeypatch.chdir(path)
-        
-        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.
-    recwarn
-        Return a WarningsRecorder instance that provides these methods:
-        
-        * ``pop(category=None)``: return last warning matching the category.
-        * ``clear()``: clear list of warnings
-        
-        See http://docs.python.org/library/warnings.html for information
-        on warning categories.
-    tmpdir_factory
-        Return a TempdirFactory instance for the test session.
-    tmpdir
-        Return a temporary directory path object
-        which is unique to each test function invocation,
-        created as a sub directory of the base temporary
-        directory.  The returned object is a `py.path.local`_
-        path object.
-    
-    no tests ran in 0.12 seconds
diff --git a/doc/en/contents.rst b/doc/en/contents.rst
index b98d0a17c..79c4fce3e 100644
--- a/doc/en/contents.rst
+++ b/doc/en/contents.rst
@@ -14,7 +14,6 @@ Full pytest documentation
    usage
    existingtestsuite
    assert
-   builtin
    fixture
    monkeypatch
    tmpdir
diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst
index 31af29da8..0965c2a61 100644
--- a/doc/en/getting-started.rst
+++ b/doc/en/getting-started.rst
@@ -172,9 +172,10 @@ Continue reading
 Check out additional pytest resources to help you customize tests for your unique workflow:
 
 * ":ref:`cmdline`" for command line invocation examples
-* ":ref:`goodpractices`" for virtualenv and test layouts
 * ":ref:`existingtestsuite`" for working with pre-existing tests
+* ":ref:`mark`" for information on the ``pytest.mark`` mechanism
 * ":ref:`fixtures`" for providing a functional baseline to your tests
 * ":ref:`plugins`" for managing and writing plugins
+* ":ref:`goodpractices`" for virtualenv and test layouts
 
 .. include:: links.inc
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index de916d511..92d69d95b 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -6,7 +6,27 @@ This page contains the full reference to pytest's API.
 
 .. contents::
     :depth: 2
-    :local: 
+    :local:
+
+
+.. autofunction:: _pytest.python_api.approx
+
+You can use the following functions in your test, fixture or setup
+functions to force a certain test outcome.  Note that most often
+you can rather use declarative marks, see :ref:`skipping`.
+
+.. autofunction:: _pytest.outcomes.fail
+.. autofunction:: _pytest.outcomes.skip
+.. autofunction:: _pytest.outcomes.importorskip
+.. autofunction:: _pytest.outcomes.xfail
+.. autofunction:: _pytest.outcomes.exit
+.. autofunction:: _pytest.config.main
+
+.. autofunction:: _pytest.python_api.raises
+
+Examples at :ref:`assertraises`.
+
+.. autofunction:: _pytest.recwarn.deprecated_call
 
 
 .. _`hook-reference`:
@@ -231,8 +251,8 @@ Example of a fixture requiring another fixture:
 For more details, consult the full :ref:`fixtures docs <fixture>`.
 
 
-fixture decorator signature
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+fixture decorator
+~~~~~~~~~~~~~~~~~
 
 .. currentmodule:: _pytest.fixtures
 .. autofunction:: fixture
@@ -346,3 +366,12 @@ doctest_namespace
             doctest_namespace['np'] = numpy
 
     For more details: :ref:`doctest_namespace`.
+
+
+request
+~~~~~~~
+
+The ``request`` fixture is a special fixture providing information of the requesting test function.
+
+.. autoclass:: _pytest.fixtures.FixtureRequest()
+    :members:

From 44e2715529e7e715c0f778011fe0b68327cd34e6 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 26 Feb 2018 20:34:53 -0300
Subject: [PATCH 13/51] Add sections to pytest's builtin API

---
 doc/en/reference.rst | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 92d69d95b..e4192f430 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -9,23 +9,57 @@ This page contains the full reference to pytest's API.
     :local:
 
 
+approx
+------
+
 .. autofunction:: _pytest.python_api.approx
 
+outcomes
+--------
+
 You can use the following functions in your test, fixture or setup
 functions to force a certain test outcome.  Note that most often
 you can rather use declarative marks, see :ref:`skipping`.
 
+fail
+~~~~
+
 .. autofunction:: _pytest.outcomes.fail
+
+skip
+~~~~
+
 .. autofunction:: _pytest.outcomes.skip
+
+importorskip
+~~~~~~~~~~~~
+
 .. autofunction:: _pytest.outcomes.importorskip
+
+xfail
+~~~~~
+
 .. autofunction:: _pytest.outcomes.xfail
+
+exit
+~~~~
+
 .. autofunction:: _pytest.outcomes.exit
+
+main
+~~~~
+
 .. autofunction:: _pytest.config.main
 
+raises
+------
 .. autofunction:: _pytest.python_api.raises
 
 Examples at :ref:`assertraises`.
 
+deprecated_call
+---------------
+
 .. autofunction:: _pytest.recwarn.deprecated_call
 
 

From 918dffba96a336e883f7086160d5b65ff751d3b3 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 26 Feb 2018 20:57:02 -0300
Subject: [PATCH 14/51] Add :with: modifier to raises() and deprecated_call()

---
 doc/en/reference.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index e4192f430..ac9bc8efb 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -53,7 +53,9 @@ main
 
 raises
 ------
+
 .. autofunction:: _pytest.python_api.raises
+    :with: excinfo
 
 Examples at :ref:`assertraises`.
 
@@ -61,7 +63,7 @@ deprecated_call
 ---------------
 
 .. autofunction:: _pytest.recwarn.deprecated_call
-
+    :with:
 
 .. _`hook-reference`:
 

From 400558cc9c9e867cc24a8ee26269abe45bcabf71 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:13:14 -0300
Subject: [PATCH 15/51] Add pytestconfig fixture

---
 doc/en/reference.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index ac9bc8efb..d89d2f1e0 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -411,3 +411,10 @@ The ``request`` fixture is a special fixture providing information of the reques
 
 .. autoclass:: _pytest.fixtures.FixtureRequest()
     :members:
+
+
+pytestconfig
+~~~~~~~~~~~~
+
+Scoped-session fixture which returns the internal :class:`_pytest.config.Config` object.
+    

From 7ba8a4ee7591ccbb78bca34ec36d7c29c81e171c Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:15:08 -0300
Subject: [PATCH 16/51] Use ``pytest.`` prefix for outcomes

---
 doc/en/reference.rst | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index d89d2f1e0..d00b20ddf 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -21,46 +21,46 @@ You can use the following functions in your test, fixture or setup
 functions to force a certain test outcome.  Note that most often
 you can rather use declarative marks, see :ref:`skipping`.
 
-fail
-~~~~
+pytest.fail
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.fail
 
-skip
-~~~~
+pytest.skip
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.skip
 
-importorskip
-~~~~~~~~~~~~
+pytest.importorskip
+~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.importorskip
 
-xfail
-~~~~~
+pytest.xfail
+~~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.xfail
 
-exit
-~~~~
+pytest.exit
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.exit
 
-main
-~~~~
+pytest.main
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.config.main
 
-raises
-------
+pytest.raises
+-------------
 
 .. autofunction:: _pytest.python_api.raises
     :with: excinfo
 
 Examples at :ref:`assertraises`.
 
-deprecated_call
----------------
+pytest.deprecated_call
+----------------------
 
 .. autofunction:: _pytest.recwarn.deprecated_call
     :with:

From 111c6d6a22a629225f8cab9c6a86da65d1bb9cab Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:19:57 -0300
Subject: [PATCH 17/51] Improve pytestconfig and add record_xml_property

---
 _pytest/fixtures.py  | 10 +++++++++-
 _pytest/junitxml.py  |  5 +++++
 doc/en/reference.rst |  7 ++++++-
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/_pytest/fixtures.py b/_pytest/fixtures.py
index 955a112b1..c4d5f726d 100644
--- a/_pytest/fixtures.py
+++ b/_pytest/fixtures.py
@@ -923,7 +923,15 @@ defaultfuncargprefixmarker = fixture()
 
 @fixture(scope="session")
 def pytestconfig(request):
-    """ the pytest config object with access to command line opts."""
+    """Session-scoped fixture that returns the :class:`_pytest.config.Config` object.
+
+    Example::
+
+        def test_foo(pytestconfig):
+            if pytestconfig.getoption("verbose"):
+                ...
+
+    """
     return request.config
 
 
diff --git a/_pytest/junitxml.py b/_pytest/junitxml.py
index e929eeba8..50f4e4084 100644
--- a/_pytest/junitxml.py
+++ b/_pytest/junitxml.py
@@ -200,6 +200,11 @@ def record_xml_property(request):
     """Add extra xml properties to the tag for the calling test.
     The fixture is callable with ``(name, value)``, with value being automatically
     xml-encoded.
+
+    Example::
+
+        def test_function(record_xml_property):
+            record_xml_property("example_key", 1)
     """
     request.node.warn(
         code='C3',
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index d00b20ddf..21ec13a43 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -416,5 +416,10 @@ The ``request`` fixture is a special fixture providing information of the reques
 pytestconfig
 ~~~~~~~~~~~~
 
-Scoped-session fixture which returns the internal :class:`_pytest.config.Config` object.
+.. autofunction:: _pytest.fixtures.pytestconfig()
     
+
+record_xml_property
+~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: _pytest.junitxml.record_xml_property()

From adcb28f61b65bc1a3913fdd33da0aa421f656278 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:32:34 -0300
Subject: [PATCH 18/51] Add caplog to reference

---
 doc/en/logging.rst   |  6 ++----
 doc/en/reference.rst | 13 ++++++++++++-
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/doc/en/logging.rst b/doc/en/logging.rst
index 82119043b..524f6edd8 100644
--- a/doc/en/logging.rst
+++ b/doc/en/logging.rst
@@ -160,11 +160,9 @@ the records for the ``setup`` and ``call`` stages during teardown like so:
                 pytest.fail('warning messages encountered during testing: {}'.format(messages))
 
 
-caplog fixture API
-~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: _pytest.logging.LogCaptureFixture
-    :members:
+The full API is available at :class:`_pytest.logging.LogCaptureFixture`.
+
 
 .. _live_logs:
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 21ec13a43..fa39f1ac7 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -5,7 +5,7 @@ Reference
 This page contains the full reference to pytest's API.
 
 .. contents::
-    :depth: 2
+    :depth: 3
     :local:
 
 
@@ -423,3 +423,14 @@ record_xml_property
 ~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: _pytest.junitxml.record_xml_property()
+
+caplog
+~~~~~~
+
+.. autofunction:: _pytest.logging.caplog()
+    :no-auto-options:
+
+    This returns a :class:`_pytest.logging.LogCaptureFixture`.
+
+.. autoclass:: _pytest.logging.LogCaptureFixture
+    :members:

From 215c6b281e82dd8642d274ba61da32960946c16f Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:48:19 -0300
Subject: [PATCH 19/51] Add Monkeypatch and tutorial links for logging

---
 _pytest/python_api.py  |  5 +++--
 doc/en/monkeypatch.rst | 12 ++++--------
 doc/en/reference.rst   | 22 +++++++++++++++++++++-
 3 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/_pytest/python_api.py b/_pytest/python_api.py
index 541371449..e5a73a353 100644
--- a/_pytest/python_api.py
+++ b/_pytest/python_api.py
@@ -547,8 +547,9 @@ def raises(expected_exception, *args, **kwargs):
     The string will be evaluated using the same ``locals()`` and ``globals()``
     at the moment of the ``raises`` call.
 
-    .. autoclass:: _pytest._code.ExceptionInfo
-        :members:
+    .. currentmodule:: _pytest._code
+
+    Consult the API of ``excinfo`` objects: :class:`ExceptionInfo`.
 
     .. note::
         Similar to caught exception objects in Python, explicitly clearing
diff --git a/doc/en/monkeypatch.rst b/doc/en/monkeypatch.rst
index 0c07b2f44..a2327d4fa 100644
--- a/doc/en/monkeypatch.rst
+++ b/doc/en/monkeypatch.rst
@@ -63,13 +63,9 @@ so that any attempts within tests to create http requests will fail.
     help although there's no guarantee.
     
 
-Method reference of the monkeypatch fixture
--------------------------------------------
+.. currentmodule:: _pytest.monkeypatch
 
-.. autoclass:: MonkeyPatch
-    :members:
-
-``monkeypatch.setattr/delattr/delitem/delenv()`` all
-by default raise an Exception if the target does not exist.
-Pass ``raising=False`` if you want to skip this check.
+API Reference
+-------------
 
+Consult the docs for the :class:`MonkeyPatch` class.
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index fa39f1ac7..e8cf441fa 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -196,6 +196,9 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
     :members:
     :show-inheritance:
 
+.. autoclass:: _pytest._code.ExceptionInfo
+    :members:
+
 .. autoclass:: _pytest.nodes.FSCollector()
     :members:
     :show-inheritance:
@@ -427,10 +430,27 @@ record_xml_property
 caplog
 ~~~~~~
 
+**Tutorial**: :doc:`logging`.
+
 .. autofunction:: _pytest.logging.caplog()
     :no-auto-options:
 
-    This returns a :class:`_pytest.logging.LogCaptureFixture`.
+    This returns a :class:`_pytest.logging.LogCaptureFixture` instance.
 
 .. autoclass:: _pytest.logging.LogCaptureFixture
     :members:
+
+
+monkeypatch
+~~~~~~~~~~~
+
+**Tutorial**: :doc:`monkeypatch`.
+
+.. autofunction:: _pytest.monkeypatch.monkeypatch()
+    :no-auto-options:
+
+    This returns a :class:`_pytest.monkeypatch.MonkeyPatch` instance.
+
+.. autoclass:: _pytest.monkeypatch.MonkeyPatch
+    :members:
+

From 66009b0f913007613f3a0cd094d4431d6e9d21ad Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 17:58:51 -0300
Subject: [PATCH 20/51] Add tutorial links to all references

---
 doc/en/example/simple.rst |  2 ++
 doc/en/reference.rst      | 25 +++++++++++++++++++++++--
 doc/en/usage.rst          |  2 ++
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst
index 8a2a92bf6..1b1cb829c 100644
--- a/doc/en/example/simple.rst
+++ b/doc/en/example/simple.rst
@@ -3,6 +3,8 @@
 Basic patterns and examples
 ==========================================================
 
+.. _request example:
+
 Pass different values to a test function, depending on command line options
 ----------------------------------------------------------------------------
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index e8cf441fa..dd77c126c 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -54,14 +54,16 @@ pytest.main
 pytest.raises
 -------------
 
+**Tutorial**: :ref:`assertraises`.
+
 .. autofunction:: _pytest.python_api.raises
     :with: excinfo
 
-Examples at :ref:`assertraises`.
-
 pytest.deprecated_call
 ----------------------
 
+**Tutorial**: :ref:`ensuring_function_triggers`.
+
 .. autofunction:: _pytest.recwarn.deprecated_call
     :with:
 
@@ -70,6 +72,7 @@ pytest.deprecated_call
 Hooks
 -----
 
+**Tutorial**: :doc:`writing_plugins`.
 
 .. currentmodule:: _pytest.hookspec
 
@@ -265,6 +268,8 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 Fixtures
 --------
 
+**Tutorial**: :ref:`fixture`.
+
 Fixtures are requested by test functions or other fixtures by declaring them as argument names.
 
 
@@ -303,6 +308,8 @@ fixture decorator
 config.cache
 ~~~~~~~~~~~~
 
+**Tutorial**: :ref:`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``.
@@ -320,6 +327,8 @@ Under the hood, the cache plugin uses the simple
 capsys
 ~~~~~~
 
+**Tutorial**: :doc:`capture`.
+
 .. currentmodule:: _pytest.capture
 
 .. autofunction:: capsys()
@@ -340,6 +349,8 @@ capsys
 capsysbinary
 ~~~~~~~~~~~~
 
+**Tutorial**: :doc:`capture`.
+
 .. autofunction:: capsysbinary()
     :no-auto-options:
 
@@ -358,6 +369,8 @@ capsysbinary
 capfd
 ~~~~~~
 
+**Tutorial**: :doc:`capture`.
+
 .. autofunction:: capfd()
     :no-auto-options:
 
@@ -376,6 +389,8 @@ capfd
 capfdbinary
 ~~~~~~~~~~~~
 
+**Tutorial**: :doc:`capture`.
+
 .. autofunction:: capfdbinary()
     :no-auto-options:
 
@@ -394,6 +409,8 @@ capfdbinary
 doctest_namespace
 ~~~~~~~~~~~~~~~~~
 
+**Tutorial**: :doc:`doctest`.
+
 .. autofunction:: _pytest.doctest.doctest_namespace()
 
     Usually this fixture is used in conjunction with another ``autouse`` fixture:
@@ -410,6 +427,8 @@ doctest_namespace
 request
 ~~~~~~~
 
+**Tutorial**: :ref:`request example`.
+
 The ``request`` fixture is a special fixture providing information of the requesting test function.
 
 .. autoclass:: _pytest.fixtures.FixtureRequest()
@@ -425,6 +444,8 @@ pytestconfig
 record_xml_property
 ~~~~~~~~~~~~~~~~~~~
 
+**Tutorial**: :ref:`record_xml_property example`.
+
 .. autofunction:: _pytest.junitxml.record_xml_property()
 
 caplog
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index abd8bac2b..4b2c49c31 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -220,6 +220,8 @@ To set the name of the root test suite xml item, you can configure the ``junit_s
     [pytest]
     junit_suite_name = my_suite
 
+.. _record_xml_property example:
+
 record_xml_property
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

From f1df6c5a6074b3f3fa16fd8cc3360c089b023a74 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 18:03:35 -0300
Subject: [PATCH 21/51] Add testdir fixture to reference

---
 doc/en/reference.rst | 40 +++++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 15 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index dd77c126c..77a8ba11a 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -250,20 +250,6 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 .. autoclass:: pluggy.PluginManager()
     :members:
 
-.. currentmodule:: _pytest.pytester
-
-.. autoclass:: Testdir()
-    :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
-
-.. autoclass:: RunResult()
-    :members:
-
-.. autoclass:: LineMatcher()
-    :members:
-
-.. autoclass:: _pytest.capture.CaptureFixture()
-    :members:
-
 
 Fixtures
 --------
@@ -465,13 +451,37 @@ caplog
 monkeypatch
 ~~~~~~~~~~~
 
+.. currentmodule:: _pytest.monkeypatch
+
 **Tutorial**: :doc:`monkeypatch`.
 
 .. autofunction:: _pytest.monkeypatch.monkeypatch()
     :no-auto-options:
 
-    This returns a :class:`_pytest.monkeypatch.MonkeyPatch` instance.
+    This returns a :class:`MonkeyPatch` instance.
 
 .. autoclass:: _pytest.monkeypatch.MonkeyPatch
     :members:
 
+testdir
+~~~~~~~
+
+.. currentmodule:: _pytest.pytester
+
+This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to
+test plugins.
+
+To use it, include in your top-most ``conftest.py`` file::
+
+    pytest_plugins = 'pytester'
+
+
+
+.. autoclass:: Testdir()
+    :members: runpytest,runpytest_subprocess,runpytest_inprocess,makeconftest,makepyfile
+
+.. autoclass:: RunResult()
+    :members:
+
+.. autoclass:: LineMatcher()
+    :members:

From f7178654e588d88c2e9f1958635762856c6c67c7 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 27 Feb 2018 18:26:40 -0300
Subject: [PATCH 22/51] Add recwarn and tmpdir fixtures to the reference docs

---
 _pytest/recwarn.py   | 13 ++++-----
 _pytest/tmpdir.py    |  2 ++
 doc/en/reference.rst | 66 ++++++++++++++++++++++++++++++++++++++++++--
 doc/en/tmpdir.rst    |  9 +++---
 doc/en/warnings.rst  | 18 ++----------
 5 files changed, 78 insertions(+), 30 deletions(-)

diff --git a/_pytest/recwarn.py b/_pytest/recwarn.py
index 4fceb10a7..ab0f79c75 100644
--- a/_pytest/recwarn.py
+++ b/_pytest/recwarn.py
@@ -16,10 +16,7 @@ from _pytest.outcomes import fail
 
 @yield_fixture
 def recwarn():
-    """Return a WarningsRecorder instance that provides these methods:
-
-    * ``pop(category=None)``: return last warning matching the category.
-    * ``clear()``: clear list of warnings
+    """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
     See http://docs.python.org/library/warnings.html for information
     on warning categories.
@@ -88,11 +85,11 @@ class _DeprecatedCallContext(object):
 def warns(expected_warning, *args, **kwargs):
     """Assert that code raises a particular class of warning.
 
-    Specifically, the input @expected_warning can be a warning class or
-    tuple of warning classes, and the code must return that warning
-    (if a single class) or one of those warnings (if a tuple).
+    Specifically, the parameter ``expected_warning`` can be a warning class or
+    sequence of warning classes, and the inside the ``with`` block must issue a warning of that class or
+    classes.
 
-    This helper produces a list of ``warnings.WarningMessage`` objects,
+    This helper produces a list of :class:`warnings.WarningMessage` objects,
     one for each warning raised.
 
     This function can be used as a context manager, or any of the other ways
diff --git a/_pytest/tmpdir.py b/_pytest/tmpdir.py
index 66b4a2d2f..315ead302 100644
--- a/_pytest/tmpdir.py
+++ b/_pytest/tmpdir.py
@@ -116,6 +116,8 @@ def tmpdir(request, tmpdir_factory):
     created as a sub directory of the base temporary
     directory.  The returned object is a `py.path.local`_
     path object.
+
+    .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
     """
     name = request.node.name
     name = re.sub(r"[\W]", "_", name)
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 77a8ba11a..a06e37007 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -9,8 +9,8 @@ This page contains the full reference to pytest's API.
     :local:
 
 
-approx
-------
+pytest.approx
+-------------
 
 .. autofunction:: _pytest.python_api.approx
 
@@ -67,6 +67,15 @@ pytest.deprecated_call
 .. autofunction:: _pytest.recwarn.deprecated_call
     :with:
 
+pytest.warns
+------------
+
+**Tutorial**: :ref:`assertwarnings`
+
+.. autofunction:: _pytest.recwarn.warns
+    :with:
+
+
 .. _`hook-reference`:
 
 Hooks
@@ -250,6 +259,10 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 .. autoclass:: pluggy.PluginManager()
     :members:
 
+.. autoclass:: pluggy.PluginManager()
+    :members:
+
+
 
 Fixtures
 --------
@@ -485,3 +498,52 @@ To use it, include in your top-most ``conftest.py`` file::
 
 .. autoclass:: LineMatcher()
     :members:
+
+
+recwarn
+~~~~~~~
+
+**Tutorial**: :ref:`assertwarnings`
+
+.. currentmodule:: _pytest.recwarn
+
+.. autofunction:: recwarn()
+    :no-auto-options:
+
+.. autoclass:: _pytest.recwarn.WarningsRecorder()
+    :members:
+
+Each recorded warning is an instance of :class:`warnings.WarningMessage`.
+
+.. note::
+    :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1
+
+.. note::
+    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
+    differently; see :ref:`ensuring_function_triggers`.
+
+
+tmpdir
+~~~~~~
+
+**Tutorial**: :doc:`tmpdir`
+
+.. currentmodule:: _pytest.tmpdir
+
+.. autofunction:: tmpdir()
+    :no-auto-options:
+
+
+tmpdir_factory
+~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`tmpdir factory example`
+
+.. _`tmpdir factory api`:
+
+``tmpdir_factory`` instances have the following methods:
+
+.. currentmodule:: _pytest.tmpdir
+
+.. automethod:: TempdirFactory.mktemp
+.. automethod:: TempdirFactory.getbasetemp
diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst
index b9c371e40..e01d359e0 100644
--- a/doc/en/tmpdir.rst
+++ b/doc/en/tmpdir.rst
@@ -51,6 +51,9 @@ Running this would result in a passed test except for the last
     test_tmpdir.py:7: AssertionError
     ========================= 1 failed in 0.12 seconds =========================
 
+
+.. _`tmpdir factory example`:
+
 The 'tmpdir_factory' fixture
 ----------------------------
 
@@ -81,12 +84,8 @@ to save time:
         img = load_image(image_file)
         # compute and test histogram
 
-``tmpdir_factory`` instances have the following methods:
+See :ref:`tmpdir_factory API <tmpdir factory api>` for details.
 
-.. currentmodule:: _pytest.tmpdir
-
-.. automethod:: TempdirFactory.mktemp
-.. automethod:: TempdirFactory.getbasetemp
 
 .. _`base temporary directory`:
 
diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index d5a627aea..df61e1f38 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -250,23 +250,11 @@ The ``recwarn`` fixture will record warnings for the whole function::
 Both ``recwarn`` and ``pytest.warns`` return the same interface for recorded
 warnings: a WarningsRecorder instance. To view the recorded warnings, you can
 iterate over this instance, call ``len`` on it to get the number of recorded
-warnings, or index into it to get a particular recorded warning. It also
-provides these methods:
+warnings, or index into it to get a particular recorded warning.
 
-.. autoclass:: _pytest.recwarn.WarningsRecorder()
-    :members:
+.. currentmodule:: _pytest.warnings
 
-Each recorded warning has the attributes ``message``, ``category``,
-``filename``, ``lineno``, ``file``, and ``line``. The ``category`` is the
-class of the warning. The ``message`` is the warning itself; calling
-``str(message)`` will return the actual message of the warning.
-
-.. note::
-    :class:`RecordedWarning` was changed from a plain class to a namedtuple in pytest 3.1
-
-.. note::
-    ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
-    differently; see :ref:`ensuring_function_triggers`.
+Full API: :class:`WarningsRecorder`.
 
 .. _`ensuring a function triggers a deprecation warning`:
 

From ed8b1efc162d4c9fbe93e1e933a053b176570ad6 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 28 Feb 2018 19:10:08 -0300
Subject: [PATCH 23/51] Add a CHANGELOG entry for the reference docs

Fix #1713
---
 changelog/1713.doc.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog/1713.doc.rst

diff --git a/changelog/1713.doc.rst b/changelog/1713.doc.rst
new file mode 100644
index 000000000..291ee3c74
--- /dev/null
+++ b/changelog/1713.doc.rst
@@ -0,0 +1 @@
+Added a `reference <https://docs.pytest.org/en/latest/reference.html>`_ page to the docs.

From 988ace9eb27ad1bab8dcec31c328d27c9549cec7 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 28 Feb 2018 20:34:20 -0300
Subject: [PATCH 24/51] Add documentation for marks

---
 _pytest/mark.py        |  15 ++++++
 _pytest/python.py      |   2 +-
 doc/en/mark.rst        |  13 -----
 doc/en/parametrize.rst |  11 +---
 doc/en/reference.rst   | 116 ++++++++++++++++++++++++++++++++++++++++-
 doc/en/skipping.rst    |  14 ++---
 6 files changed, 137 insertions(+), 34 deletions(-)

diff --git a/_pytest/mark.py b/_pytest/mark.py
index 3cac9dc91..ef7b937e9 100644
--- a/_pytest/mark.py
+++ b/_pytest/mark.py
@@ -116,6 +116,21 @@ class MarkerError(Exception):
 
 
 def param(*values, **kw):
+    """Specify a parameter in a `pytest.mark.parametrize`_ call.
+
+    .. code-block:: python
+
+        @pytest.mark.parametrize("test_input,expected", [
+            ("3+5", 8),
+            pytest.param("6*9", 42, marks=pytest.mark.xfail),
+        ])
+        def test_eval(test_input, expected):
+            assert eval(test_input) == expected
+
+    :param values: variable args of the values of the parameter set, in order.
+    :keyword marks: a single mark or a list of marks to be applied to this parameter set.
+    :keyword str id: the id to attribute to this parameter set.
+    """
     return ParameterSet.param(*values, **kw)
 
 
diff --git a/_pytest/python.py b/_pytest/python.py
index fb7bac8b8..d299d0987 100644
--- a/_pytest/python.py
+++ b/_pytest/python.py
@@ -717,7 +717,7 @@ class CallSpec2(object):
 
 class Metafunc(fixtures.FuncargnamesCompatAttr):
     """
-    Metafunc objects are passed to the ``pytest_generate_tests`` hook.
+    Metafunc objects are passed to the :func:`pytest_generate_tests <_pytest.hookspec.pytest_generate_tests>` hook.
     They help to inspect a test function and to generate tests according to
     test configuration or values specified in the class or module where a
     test function is defined.
diff --git a/doc/en/mark.rst b/doc/en/mark.rst
index 0b0e072a0..e4858bf83 100644
--- a/doc/en/mark.rst
+++ b/doc/en/mark.rst
@@ -4,7 +4,6 @@
 Marking test functions with attributes
 =================================================================
 
-.. currentmodule:: _pytest.mark
 
 By using the ``pytest.mark`` helper you can easily set
 metadata on your test functions. There are
@@ -27,15 +26,3 @@ which also serve as documentation.
     :ref:`fixtures <fixtures>`.
 
 
-API reference for mark related objects
-------------------------------------------------
-
-.. autoclass:: MarkGenerator
-    :members:
-
-.. autoclass:: MarkDecorator
-    :members:
-
-.. autoclass:: MarkInfo
-    :members:
-
diff --git a/doc/en/parametrize.rst b/doc/en/parametrize.rst
index 991dd4b1e..ba2cd3cce 100644
--- a/doc/en/parametrize.rst
+++ b/doc/en/parametrize.rst
@@ -33,7 +33,7 @@ pytest enables test parametrization at several levels:
 .. versionchanged:: 2.4
     Several improvements.
 
-The builtin ``pytest.mark.parametrize`` decorator enables
+The builtin :ref:`pytest.mark.parametrize ref` decorator enables
 parametrization of arguments for a test function.  Here is a typical example
 of a test function that implements checking that a certain input leads
 to an expected output::
@@ -206,12 +206,3 @@ More examples
 
 For further examples, you might want to look at :ref:`more
 parametrization examples <paramexamples>`.
-
-.. _`metafunc object`:
-
-The **metafunc** object
--------------------------------------------
-
-.. currentmodule:: _pytest.python
-.. autoclass:: Metafunc
-    :members:
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index a06e37007..1beaa3bfb 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -51,6 +51,11 @@ pytest.main
 
 .. autofunction:: _pytest.config.main
 
+pytest.param
+~~~~~~~~~~~~
+
+.. autofunction:: _pytest.mark.param
+
 pytest.raises
 -------------
 
@@ -246,6 +251,10 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
     :members:
     :inherited-members:
 
+.. currentmodule:: _pytest.python
+.. autoclass:: Metafunc
+    :members:
+
 .. autoclass:: pluggy._Result
     :members:
 
@@ -259,9 +268,114 @@ Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
 .. autoclass:: pluggy.PluginManager()
     :members:
 
-.. autoclass:: pluggy.PluginManager()
+.. currentmodule:: _pytest.mark
+
+.. autoclass:: MarkGenerator
     :members:
 
+.. autoclass:: MarkDecorator
+    :members:
+
+.. autoclass:: MarkInfo
+    :members:
+
+
+Marks
+-----
+
+Marks can be used apply meta data to *test functions* (but not fixtures), which can then be accessed by
+fixtures or plugins.
+
+
+.. _`pytest.mark.parametrize ref`:
+
+pytest.mark.parametrize
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :doc:`parametrize`.
+
+.. automethod:: _pytest.python.Metafunc.parametrize
+
+
+.. _`pytest.mark.skip ref`:
+
+pytest.mark.skip
+~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`skip`.
+
+Unconditionally skip a test function.
+
+.. py:function:: pytest.mark.skip(*, reason=None)
+
+    :keyword str reason: Reason why the test function is being skipped.
+
+
+.. _`pytest.mark.skipif ref`:
+
+pytest.mark.skipif
+~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`xfail`.
+
+Skip a test function if a condition is ``True``.
+
+.. py:function:: pytest.mark.skipif(condition, *, reason=None)
+
+    :type condition: bool or str
+    :param condition: ``True/False`` if the condition should be skipped or a :ref:`condition string <string conditions>`.
+    :keyword str reason: Reason why the test function is being skipped.
+
+
+.. _`pytest.mark.xfail ref`:
+
+pytest.mark.xfail
+~~~~~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`xfail`.
+
+Marks a test function as *expected to fail*.
+
+.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False)
+
+    :type condition: bool or str
+    :param condition: ``True/False`` if the condition should be marked as xfail or a :ref:`condition string <string conditions>`.
+    :keyword str reason: Reason why the test function is marked as xfail.
+    :keyword Exception raises: Exception subclass expected to be raised by the test function; other exceptions will fail the test.
+    :keyword bool run:
+        If the test function should actually be executed. If ``False``, the function will always xfail and will
+        not be executed (useful a function is segfaulting).
+    :keyword bool strict:
+        * If ``False`` (the default) the function will be shown in the terminal output as ``xfailed`` if it fails
+          and as ``xpass`` if it passes. In both cases this will not cause the test suite to fail as a whole. This
+          is particularly useful to mark *flaky* tests (tests that random at fail) to be tackled later.
+        * If ``True``, the function will be shown in the terminal output as ``xfailed`` if it fails, but if it
+          unexpectedly passes then it will **fail** the test suite. This is particularly useful to mark functions
+          that are always failing and there should be a clear indication if they unexpectedly start to pass (for example
+          a new release of a library fixes a known bug).
+
+
+custom marks
+~~~~~~~~~~~~
+
+Marks are created dynamically using the factory object ``pytest.mark`` and applied as a decorator.
+
+For example:
+
+.. code-block:: python
+
+    @pytest.mark.timeout(10, 'slow', method='thread')
+    def test_function():
+        ...
+
+Will create and attach a :class:`MarkInfo <_pytest.mark.MarkInfo>` object to the collected
+:class:`Item <_pytest.nodes.Item>`, which can then be accessed by fixtures or hooks with
+:meth:`Node.get_marker <_pytest.nodes.Node.get_marker>`. The ``mark`` object will have the following attributes:
+
+.. code-block:: python
+
+    mark.args == (10, 'slow')
+    mark.kwargs == {'method': 'thread'}
 
 
 Fixtures
diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst
index 7e001929b..195674199 100644
--- a/doc/en/skipping.rst
+++ b/doc/en/skipping.rst
@@ -71,6 +71,8 @@ It is also possible to skip the whole module using
 The imperative method is useful when it is not possible to evaluate the skip condition
 during import time.
 
+**Reference**: :ref:`pytest.mark.skip ref`
+
 ``skipif``
 ~~~~~~~~~~
 
@@ -116,6 +118,8 @@ Alternatively, you can use :ref:`condition strings
 <string conditions>` instead of booleans, but they can't be shared between modules easily
 so they are supported mainly for backward compatibility reasons.
 
+**Reference**: :ref:`pytest.mark.skipif ref`
+
 
 Skip all test functions of a class or module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -232,15 +236,7 @@ This will unconditionally make ``test_function`` ``XFAIL``. Note that no other c
 after ``pytest.xfail`` call, differently from the marker. That's because it is implemented
 internally by raising a known exception.
 
-Here's the signature of the ``xfail`` **marker** (not the function), using Python 3 keyword-only
-arguments syntax:
-
-.. code-block:: python
-
-    def xfail(condition=None, *, reason=None, raises=None, run=True, strict=False):
-
-
-
+**Reference**: :ref:`pytest.mark.xfail ref`
 
 ``strict`` parameter
 ~~~~~~~~~~~~~~~~~~~~

From df3a4111a97756156a28bde6da53ddfc230abb84 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 28 Feb 2018 20:48:54 -0300
Subject: [PATCH 25/51] Sort objects by name

---
 doc/en/reference.rst | 152 ++++++++++++++++++++++++++++++-------------
 1 file changed, 106 insertions(+), 46 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 1beaa3bfb..1a5deca05 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -198,88 +198,148 @@ reporting or interaction with exceptions:
 Objects
 -------
 
-Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks
+Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks.
 
-.. autoclass:: _pytest.config.Config()
+
+CallInfo
+~~~~~~~~
+
+.. autoclass:: _pytest.runner.CallInfo()
     :members:
 
-.. autoclass:: _pytest.config.Parser()
-    :members:
 
-.. autoclass:: _pytest.nodes.Node()
-    :members:
-
-.. autoclass:: _pytest.nodes.Collector()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest._code.ExceptionInfo
-    :members:
-
-.. autoclass:: _pytest.nodes.FSCollector()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.main.Session()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.nodes.Item()
-    :members:
-    :show-inheritance:
-
-.. autoclass:: _pytest.python.Module()
-    :members:
-    :show-inheritance:
+Class
+~~~~~
 
 .. autoclass:: _pytest.python.Class()
     :members:
     :show-inheritance:
 
-.. autoclass:: _pytest.python.Function()
+Collector
+~~~~~~~~~
+
+.. autoclass:: _pytest.nodes.Collector()
     :members:
     :show-inheritance:
 
+Config
+~~~~~~
+
+.. autoclass:: _pytest.config.Config()
+    :members:
+
+ExceptionInfo
+~~~~~~~~~~~~~
+
+.. autoclass:: _pytest._code.ExceptionInfo
+    :members:
+
+FixtureDef
+~~~~~~~~~~
+
 .. autoclass:: _pytest.fixtures.FixtureDef()
     :members:
     :show-inheritance:
 
-.. autoclass:: _pytest.runner.CallInfo()
+FSCollector
+~~~~~~~~~~~
+
+.. autoclass:: _pytest.nodes.FSCollector()
+    :members:
+    :show-inheritance:
+
+Function
+~~~~~~~~
+
+.. autoclass:: _pytest.python.Function()
+    :members:
+    :show-inheritance:
+
+Item
+~~~~
+
+.. autoclass:: _pytest.nodes.Item()
+    :members:
+    :show-inheritance:
+
+MarkDecorator
+~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.mark.MarkDecorator
     :members:
 
-.. autoclass:: _pytest.runner.TestReport()
-    :members:
-    :inherited-members:
+MarkGenerator
+~~~~~~~~~~~~~
 
-.. currentmodule:: _pytest.python
-.. autoclass:: Metafunc
+.. autoclass:: _pytest.mark.MarkGenerator
     :members:
 
-.. autoclass:: pluggy._Result
+MarkInfo
+~~~~~~~~
+
+.. autoclass:: _pytest.mark.MarkInfo
     :members:
 
-.. autofunction:: _pytest.config.get_plugin_manager()
+Metafunc
+~~~~~~~~
+
+.. autoclass:: _pytest.python.Metafunc
+    :members:
+
+Module
+~~~~~~
+
+.. autoclass:: _pytest.python.Module()
+    :members:
+    :show-inheritance:
+
+Node
+~~~~
+
+.. autoclass:: _pytest.nodes.Node()
+    :members:
+
+Parser
+~~~~~~
+
+.. autoclass:: _pytest.config.Parser()
+    :members:
+
+PluginManager
+~~~~~~~~~~~~~
+
+.. autoclass:: pluggy.PluginManager()
+    :members:
+
+
+PytestPluginManager
+~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: _pytest.config.PytestPluginManager()
     :members:
     :undoc-members:
     :show-inheritance:
 
-.. autoclass:: pluggy.PluginManager()
+Session
+~~~~~~~
+
+.. autoclass:: _pytest.main.Session()
     :members:
+    :show-inheritance:
 
-.. currentmodule:: _pytest.mark
+TestReport
+~~~~~~~~~~
 
-.. autoclass:: MarkGenerator
+.. autoclass:: _pytest.runner.TestReport()
     :members:
+    :inherited-members:
 
-.. autoclass:: MarkDecorator
+_Result
+~~~~~~~
+
+.. autoclass:: pluggy._Result
     :members:
 
-.. autoclass:: MarkInfo
-    :members:
-
-
 Marks
 -----
 

From 9c2203d3818dae3becf7abfa3395c7e86b629be6 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 28 Feb 2018 20:52:41 -0300
Subject: [PATCH 26/51] Reorder top level: functions, marks, fixtures, hooks
 and objects

---
 doc/en/reference.rst | 522 +++++++++++++++++++++----------------------
 1 file changed, 261 insertions(+), 261 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 1a5deca05..70cda3b84 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -80,266 +80,6 @@ pytest.warns
 .. autofunction:: _pytest.recwarn.warns
     :with:
 
-
-.. _`hook-reference`:
-
-Hooks
------
-
-**Tutorial**: :doc:`writing_plugins`.
-
-.. currentmodule:: _pytest.hookspec
-
-Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
-
-Bootstrapping hooks
-~~~~~~~~~~~~~~~~~~~
-
-Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
-
-.. autofunction:: pytest_load_initial_conftests
-.. autofunction:: pytest_cmdline_preparse
-.. autofunction:: pytest_cmdline_parse
-.. autofunction:: pytest_cmdline_main
-
-Initialization hooks
-~~~~~~~~~~~~~~~~~~~~
-
-Initialization hooks called for plugins and ``conftest.py`` files.
-
-.. autofunction:: pytest_addoption
-.. autofunction:: pytest_configure
-.. autofunction:: pytest_unconfigure
-
-Test running hooks
-~~~~~~~~~~~~~~~~~~
-
-All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
-
-.. autofunction:: pytest_runtestloop
-.. autofunction:: pytest_runtest_protocol
-.. autofunction:: pytest_runtest_logstart
-.. autofunction:: pytest_runtest_logfinish
-.. autofunction:: pytest_runtest_setup
-.. autofunction:: pytest_runtest_call
-.. autofunction:: pytest_runtest_teardown
-.. autofunction:: pytest_runtest_makereport
-
-For deeper understanding you may look at the default implementation of
-these hooks in :py:mod:`_pytest.runner` and maybe also
-in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
-and its input/output capturing in order to immediately drop
-into interactive debugging when a test failure occurs.
-
-The :py:mod:`_pytest.terminal` reported specifically uses
-the reporting hook to print information about a test run.
-
-Collection hooks
-~~~~~~~~~~~~~~~~
-
-``pytest`` calls the following hooks for collecting files and directories:
-
-.. autofunction:: pytest_collection
-.. autofunction:: pytest_ignore_collect
-.. autofunction:: pytest_collect_directory
-.. autofunction:: pytest_collect_file
-
-For influencing the collection of objects in Python modules
-you can use the following hook:
-
-.. autofunction:: pytest_pycollect_makeitem
-.. autofunction:: pytest_generate_tests
-.. autofunction:: pytest_make_parametrize_id
-
-After collection is complete, you can modify the order of
-items, delete or otherwise amend the test items:
-
-.. autofunction:: pytest_collection_modifyitems
-
-Reporting hooks
-~~~~~~~~~~~~~~~
-
-Session related reporting hooks:
-
-.. autofunction:: pytest_collectstart
-.. autofunction:: pytest_itemcollected
-.. autofunction:: pytest_collectreport
-.. autofunction:: pytest_deselected
-.. autofunction:: pytest_report_header
-.. autofunction:: pytest_report_collectionfinish
-.. autofunction:: pytest_report_teststatus
-.. autofunction:: pytest_terminal_summary
-.. autofunction:: pytest_fixture_setup
-.. autofunction:: pytest_fixture_post_finalizer
-
-And here is the central hook for reporting about
-test execution:
-
-.. autofunction:: pytest_runtest_logreport
-
-You can also use this hook to customize assertion representation for some
-types:
-
-.. autofunction:: pytest_assertrepr_compare
-
-
-Debugging/Interaction hooks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are few hooks which can be used for special
-reporting or interaction with exceptions:
-
-.. autofunction:: pytest_internalerror
-.. autofunction:: pytest_keyboard_interrupt
-.. autofunction:: pytest_exception_interact
-.. autofunction:: pytest_enter_pdb
-
-
-Objects
--------
-
-Full reference to objects accessible from :ref:`fixtures <fixture>` or hooks.
-
-
-CallInfo
-~~~~~~~~
-
-.. autoclass:: _pytest.runner.CallInfo()
-    :members:
-
-
-Class
-~~~~~
-
-.. autoclass:: _pytest.python.Class()
-    :members:
-    :show-inheritance:
-
-Collector
-~~~~~~~~~
-
-.. autoclass:: _pytest.nodes.Collector()
-    :members:
-    :show-inheritance:
-
-Config
-~~~~~~
-
-.. autoclass:: _pytest.config.Config()
-    :members:
-
-ExceptionInfo
-~~~~~~~~~~~~~
-
-.. autoclass:: _pytest._code.ExceptionInfo
-    :members:
-
-FixtureDef
-~~~~~~~~~~
-
-.. autoclass:: _pytest.fixtures.FixtureDef()
-    :members:
-    :show-inheritance:
-
-FSCollector
-~~~~~~~~~~~
-
-.. autoclass:: _pytest.nodes.FSCollector()
-    :members:
-    :show-inheritance:
-
-Function
-~~~~~~~~
-
-.. autoclass:: _pytest.python.Function()
-    :members:
-    :show-inheritance:
-
-Item
-~~~~
-
-.. autoclass:: _pytest.nodes.Item()
-    :members:
-    :show-inheritance:
-
-MarkDecorator
-~~~~~~~~~~~~~
-
-.. autoclass:: _pytest.mark.MarkDecorator
-    :members:
-
-MarkGenerator
-~~~~~~~~~~~~~
-
-.. autoclass:: _pytest.mark.MarkGenerator
-    :members:
-
-MarkInfo
-~~~~~~~~
-
-.. autoclass:: _pytest.mark.MarkInfo
-    :members:
-
-Metafunc
-~~~~~~~~
-
-.. autoclass:: _pytest.python.Metafunc
-    :members:
-
-Module
-~~~~~~
-
-.. autoclass:: _pytest.python.Module()
-    :members:
-    :show-inheritance:
-
-Node
-~~~~
-
-.. autoclass:: _pytest.nodes.Node()
-    :members:
-
-Parser
-~~~~~~
-
-.. autoclass:: _pytest.config.Parser()
-    :members:
-
-PluginManager
-~~~~~~~~~~~~~
-
-.. autoclass:: pluggy.PluginManager()
-    :members:
-
-
-PytestPluginManager
-~~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: _pytest.config.PytestPluginManager()
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Session
-~~~~~~~
-
-.. autoclass:: _pytest.main.Session()
-    :members:
-    :show-inheritance:
-
-TestReport
-~~~~~~~~~~
-
-.. autoclass:: _pytest.runner.TestReport()
-    :members:
-    :inherited-members:
-
-_Result
-~~~~~~~
-
-.. autoclass:: pluggy._Result
-    :members:
-
 Marks
 -----
 
@@ -612,7 +352,7 @@ pytestconfig
 ~~~~~~~~~~~~
 
 .. autofunction:: _pytest.fixtures.pytestconfig()
-    
+
 
 record_xml_property
 ~~~~~~~~~~~~~~~~~~~
@@ -721,3 +461,263 @@ tmpdir_factory
 
 .. automethod:: TempdirFactory.mktemp
 .. automethod:: TempdirFactory.getbasetemp
+
+
+.. _`hook-reference`:
+
+Hooks
+-----
+
+**Tutorial**: :doc:`writing_plugins`.
+
+.. currentmodule:: _pytest.hookspec
+
+Reference to all hooks which can be implemented by :ref:`conftest.py files <localplugin>` and :ref:`plugins <plugins>`.
+
+Bootstrapping hooks
+~~~~~~~~~~~~~~~~~~~
+
+Bootstrapping hooks called for plugins registered early enough (internal and setuptools plugins).
+
+.. autofunction:: pytest_load_initial_conftests
+.. autofunction:: pytest_cmdline_preparse
+.. autofunction:: pytest_cmdline_parse
+.. autofunction:: pytest_cmdline_main
+
+Initialization hooks
+~~~~~~~~~~~~~~~~~~~~
+
+Initialization hooks called for plugins and ``conftest.py`` files.
+
+.. autofunction:: pytest_addoption
+.. autofunction:: pytest_configure
+.. autofunction:: pytest_unconfigure
+
+Test running hooks
+~~~~~~~~~~~~~~~~~~
+
+All runtest related hooks receive a :py:class:`pytest.Item <_pytest.main.Item>` object.
+
+.. autofunction:: pytest_runtestloop
+.. autofunction:: pytest_runtest_protocol
+.. autofunction:: pytest_runtest_logstart
+.. autofunction:: pytest_runtest_logfinish
+.. autofunction:: pytest_runtest_setup
+.. autofunction:: pytest_runtest_call
+.. autofunction:: pytest_runtest_teardown
+.. autofunction:: pytest_runtest_makereport
+
+For deeper understanding you may look at the default implementation of
+these hooks in :py:mod:`_pytest.runner` and maybe also
+in :py:mod:`_pytest.pdb` which interacts with :py:mod:`_pytest.capture`
+and its input/output capturing in order to immediately drop
+into interactive debugging when a test failure occurs.
+
+The :py:mod:`_pytest.terminal` reported specifically uses
+the reporting hook to print information about a test run.
+
+Collection hooks
+~~~~~~~~~~~~~~~~
+
+``pytest`` calls the following hooks for collecting files and directories:
+
+.. autofunction:: pytest_collection
+.. autofunction:: pytest_ignore_collect
+.. autofunction:: pytest_collect_directory
+.. autofunction:: pytest_collect_file
+
+For influencing the collection of objects in Python modules
+you can use the following hook:
+
+.. autofunction:: pytest_pycollect_makeitem
+.. autofunction:: pytest_generate_tests
+.. autofunction:: pytest_make_parametrize_id
+
+After collection is complete, you can modify the order of
+items, delete or otherwise amend the test items:
+
+.. autofunction:: pytest_collection_modifyitems
+
+Reporting hooks
+~~~~~~~~~~~~~~~
+
+Session related reporting hooks:
+
+.. autofunction:: pytest_collectstart
+.. autofunction:: pytest_itemcollected
+.. autofunction:: pytest_collectreport
+.. autofunction:: pytest_deselected
+.. autofunction:: pytest_report_header
+.. autofunction:: pytest_report_collectionfinish
+.. autofunction:: pytest_report_teststatus
+.. autofunction:: pytest_terminal_summary
+.. autofunction:: pytest_fixture_setup
+.. autofunction:: pytest_fixture_post_finalizer
+
+And here is the central hook for reporting about
+test execution:
+
+.. autofunction:: pytest_runtest_logreport
+
+You can also use this hook to customize assertion representation for some
+types:
+
+.. autofunction:: pytest_assertrepr_compare
+
+
+Debugging/Interaction hooks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are few hooks which can be used for special
+reporting or interaction with exceptions:
+
+.. autofunction:: pytest_internalerror
+.. autofunction:: pytest_keyboard_interrupt
+.. autofunction:: pytest_exception_interact
+.. autofunction:: pytest_enter_pdb
+
+
+Objects
+-------
+
+Full reference to objects accessible from :ref:`fixtures <fixture>` or :ref:`hooks <hook-reference>`.
+
+
+CallInfo
+~~~~~~~~
+
+.. autoclass:: _pytest.runner.CallInfo()
+    :members:
+
+
+Class
+~~~~~
+
+.. autoclass:: _pytest.python.Class()
+    :members:
+    :show-inheritance:
+
+Collector
+~~~~~~~~~
+
+.. autoclass:: _pytest.nodes.Collector()
+    :members:
+    :show-inheritance:
+
+Config
+~~~~~~
+
+.. autoclass:: _pytest.config.Config()
+    :members:
+
+ExceptionInfo
+~~~~~~~~~~~~~
+
+.. autoclass:: _pytest._code.ExceptionInfo
+    :members:
+
+FixtureDef
+~~~~~~~~~~
+
+.. autoclass:: _pytest.fixtures.FixtureDef()
+    :members:
+    :show-inheritance:
+
+FSCollector
+~~~~~~~~~~~
+
+.. autoclass:: _pytest.nodes.FSCollector()
+    :members:
+    :show-inheritance:
+
+Function
+~~~~~~~~
+
+.. autoclass:: _pytest.python.Function()
+    :members:
+    :show-inheritance:
+
+Item
+~~~~
+
+.. autoclass:: _pytest.nodes.Item()
+    :members:
+    :show-inheritance:
+
+MarkDecorator
+~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.mark.MarkDecorator
+    :members:
+
+MarkGenerator
+~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.mark.MarkGenerator
+    :members:
+
+MarkInfo
+~~~~~~~~
+
+.. autoclass:: _pytest.mark.MarkInfo
+    :members:
+
+Metafunc
+~~~~~~~~
+
+.. autoclass:: _pytest.python.Metafunc
+    :members:
+
+Module
+~~~~~~
+
+.. autoclass:: _pytest.python.Module()
+    :members:
+    :show-inheritance:
+
+Node
+~~~~
+
+.. autoclass:: _pytest.nodes.Node()
+    :members:
+
+Parser
+~~~~~~
+
+.. autoclass:: _pytest.config.Parser()
+    :members:
+
+PluginManager
+~~~~~~~~~~~~~
+
+.. autoclass:: pluggy.PluginManager()
+    :members:
+
+
+PytestPluginManager
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.config.PytestPluginManager()
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Session
+~~~~~~~
+
+.. autoclass:: _pytest.main.Session()
+    :members:
+    :show-inheritance:
+
+TestReport
+~~~~~~~~~~
+
+.. autoclass:: _pytest.runner.TestReport()
+    :members:
+    :inherited-members:
+
+_Result
+~~~~~~~
+
+.. autoclass:: pluggy._Result
+    :members:

From 8b7e6df73d67953e949cf5605954d9c43a0fd5f7 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 1 Mar 2018 17:54:54 -0300
Subject: [PATCH 27/51] Add register_assert_rewrite and improve signature of
 other functions

---
 doc/en/reference.rst       | 23 +++++++++++++++--------
 doc/en/writing_plugins.rst |  3 +++
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 70cda3b84..b30d02052 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -29,7 +29,7 @@ pytest.fail
 pytest.skip
 ~~~~~~~~~~~
 
-.. autofunction:: _pytest.outcomes.skip
+.. autofunction:: _pytest.outcomes.skip(msg, [allow_module_level=False])
 
 pytest.importorskip
 ~~~~~~~~~~~~~~~~~~~
@@ -42,26 +42,26 @@ pytest.xfail
 .. autofunction:: _pytest.outcomes.xfail
 
 pytest.exit
-~~~~~~~~~~~
+-----------
 
 .. autofunction:: _pytest.outcomes.exit
 
 pytest.main
-~~~~~~~~~~~
+-----------
 
 .. autofunction:: _pytest.config.main
 
 pytest.param
-~~~~~~~~~~~~
+------------
 
-.. autofunction:: _pytest.mark.param
+.. autofunction:: pytest.param(*values, [id], [marks])
 
 pytest.raises
 -------------
 
 **Tutorial**: :ref:`assertraises`.
 
-.. autofunction:: _pytest.python_api.raises
+.. autofunction:: pytest.raises(expected_exception: Exception, [match], [message])
     :with: excinfo
 
 pytest.deprecated_call
@@ -69,15 +69,22 @@ pytest.deprecated_call
 
 **Tutorial**: :ref:`ensuring_function_triggers`.
 
-.. autofunction:: _pytest.recwarn.deprecated_call
+.. autofunction:: pytest.deprecated_call()
     :with:
 
+pytest.register_assert_rewrite
+------------------------------
+
+**Tutorial**: :ref:`assertion-rewriting`.
+
+.. autofunction:: pytest.register_assert_rewrite
+
 pytest.warns
 ------------
 
 **Tutorial**: :ref:`assertwarnings`
 
-.. autofunction:: _pytest.recwarn.warns
+.. autofunction:: pytest.warns(expected_warning: Exception, [match])
     :with:
 
 Marks
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index 55f692a6a..33a362a8a 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -176,6 +176,8 @@ If a package is installed this way, ``pytest`` will load
     to make it easy for users to find your plugin.
 
 
+.. _assertion-rewriting:
+
 Assertion Rewriting
 -------------------
 
@@ -196,6 +198,7 @@ assertion rewriting to be enabled you need to ask ``pytest``
 explicitly to rewrite this module before it gets imported.
 
 .. autofunction:: pytest.register_assert_rewrite
+    :noindex:
 
 This is especially important when you write a pytest plugin which is
 created using a package.  The import hook only treats ``conftest.py``

From 69d49f18e900cc9127da3f306ed353fe7ca98083 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 1 Mar 2018 17:55:45 -0300
Subject: [PATCH 28/51] Add pytest_addhooks

---
 doc/en/reference.rst       | 1 +
 doc/en/writing_plugins.rst | 1 +
 2 files changed, 2 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index b30d02052..6637ceb1f 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -497,6 +497,7 @@ Initialization hooks
 Initialization hooks called for plugins and ``conftest.py`` files.
 
 .. autofunction:: pytest_addoption
+.. autofunction:: pytest_addhooks
 .. autofunction:: pytest_configure
 .. autofunction:: pytest_unconfigure
 
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index 33a362a8a..dab88da22 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -543,6 +543,7 @@ implemented by other plugins in order to alter behaviour or interact with
 the new plugin:
 
 .. autofunction:: pytest_addhooks
+    :noindex:
 
 Hooks are usually declared as do-nothing functions that contain only
 documentation describing when the hook will be called and what return values

From 443888248a152b69aee9fcd4bceb478875c46b5a Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 1 Mar 2018 18:07:06 -0300
Subject: [PATCH 29/51] Improve fixture reference a bit

---
 doc/en/reference.rst | 34 +++++++++++++++-------------------
 1 file changed, 15 insertions(+), 19 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 6637ceb1f..415c618ba 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -8,22 +8,19 @@ This page contains the full reference to pytest's API.
     :depth: 3
     :local:
 
+Functions
+---------
 
 pytest.approx
--------------
+~~~~~~~~~~~~~
 
 .. autofunction:: _pytest.python_api.approx
 
-outcomes
---------
-
-You can use the following functions in your test, fixture or setup
-functions to force a certain test outcome.  Note that most often
-you can rather use declarative marks, see :ref:`skipping`.
-
 pytest.fail
 ~~~~~~~~~~~
 
+**Tutorial**: :ref:`skipping`
+
 .. autofunction:: _pytest.outcomes.fail
 
 pytest.skip
@@ -42,22 +39,22 @@ pytest.xfail
 .. autofunction:: _pytest.outcomes.xfail
 
 pytest.exit
------------
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.outcomes.exit
 
 pytest.main
------------
+~~~~~~~~~~~
 
 .. autofunction:: _pytest.config.main
 
 pytest.param
-------------
+~~~~~~~~~~~~~
 
 .. autofunction:: pytest.param(*values, [id], [marks])
 
 pytest.raises
--------------
+~~~~~~~~~~~~~
 
 **Tutorial**: :ref:`assertraises`.
 
@@ -65,7 +62,7 @@ pytest.raises
     :with: excinfo
 
 pytest.deprecated_call
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 **Tutorial**: :ref:`ensuring_function_triggers`.
 
@@ -73,14 +70,14 @@ pytest.deprecated_call
     :with:
 
 pytest.register_assert_rewrite
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 **Tutorial**: :ref:`assertion-rewriting`.
 
 .. autofunction:: pytest.register_assert_rewrite
 
 pytest.warns
-------------
+~~~~~~~~~~~~
 
 **Tutorial**: :ref:`assertwarnings`
 
@@ -215,11 +212,10 @@ Example of a fixture requiring another fixture:
 For more details, consult the full :ref:`fixtures docs <fixture>`.
 
 
-fixture decorator
-~~~~~~~~~~~~~~~~~
+@pytest.fixture
+~~~~~~~~~~~~~~~
 
-.. currentmodule:: _pytest.fixtures
-.. autofunction:: fixture
+.. autofunction:: pytest.fixture
     :decorator:
 
 

From 3979f9ba3a47d3c7a6fd6579438a257d6feceb58 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 1 Mar 2018 18:20:55 -0300
Subject: [PATCH 30/51] Add pytest_plugins and pytestmark special variables

---
 doc/en/plugins.rst   |  3 ++-
 doc/en/reference.rst | 47 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/doc/en/plugins.rst b/doc/en/plugins.rst
index 276b394d0..4089b9b28 100644
--- a/doc/en/plugins.rst
+++ b/doc/en/plugins.rst
@@ -61,10 +61,11 @@ status against different pytest and Python versions, please visit
 
 You may also discover more plugins through a `pytest- pypi.python.org search`_.
 
-.. _`available installable plugins`:
 .. _`pytest- pypi.python.org search`: http://pypi.python.org/pypi?%3Aaction=search&term=pytest-&submit=search
 
 
+.. _`available installable plugins`:
+
 Requiring/Loading plugins in a test module or conftest file
 -----------------------------------------------------------
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 415c618ba..8cf95a818 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -84,6 +84,9 @@ pytest.warns
 .. autofunction:: pytest.warns(expected_warning: Exception, [match])
     :with:
 
+
+.. _`marks ref`:
+
 Marks
 -----
 
@@ -725,3 +728,47 @@ _Result
 
 .. autoclass:: pluggy._Result
     :members:
+
+Special Variables
+-----------------
+
+pytest treats some global variables in a special manner when defined in a test module.
+
+
+pytest_plugins
+~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`available installable plugins`
+
+Can be declared at the **global** level in *test modules* and *conftest.py files* to register additional plugins.
+Can be either a ``str`` or ``Sequence[str]``.
+
+.. code-block:: python
+
+    pytest_plugins = "myapp.testsupport.myplugin"
+
+.. code-block:: python
+
+    pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression")
+
+
+pytest_mark
+~~~~~~~~~~~
+
+**Tutorial**: :ref:`scoped-marking`
+
+Can be declared at the **global** level in *test modules* to apply one or more :ref:`marks <marks ref>` to all
+test functions and methods. Can be either a single mark or a sequence of marks.
+
+.. code-block:: python
+
+    import pytest
+    pytestmark = pytest.mark.webtest
+
+
+.. code-block:: python
+
+    import pytest
+    pytestmark = (pytest.mark.integration, pytest.mark.slow)
+
+

From 18a47bfd22bb93ad5875281ff82fd0efaf68156e Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Thu, 1 Mar 2018 23:33:21 -0300
Subject: [PATCH 31/51] Add docs for CaptureFixture

---
 _pytest/capture.py   | 5 ++---
 doc/en/reference.rst | 3 +++
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/_pytest/capture.py b/_pytest/capture.py
index 5171358ef..71b49a257 100644
--- a/_pytest/capture.py
+++ b/_pytest/capture.py
@@ -292,10 +292,9 @@ class CaptureFixture(object):
             cap.stop_capturing()
 
     def readouterr(self):
-        """Read and return the captured output so far.
+        """Read and return the captured output so far, resetting the internal buffer.
 
-        :rtype: Tuple[str, str]
-        :return: captured content as a pair of (stdout, stdout) strings
+        :return: captured content as a namedtuple with  ``out`` and ``err`` string attributes
         """
         try:
             return self._capture.readouterr()
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 8cf95a818..6a39f7542 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -264,6 +264,9 @@ capsys
             captured = capsys.readouterr()
             assert captured.out == "hello\n"
 
+.. autoclass:: CaptureFixture()
+    :members:
+
 
 capsysbinary
 ~~~~~~~~~~~~

From c0fe4d483d6356b0fb6b2dc5e2e06792e866b726 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 6 Mar 2018 20:40:07 -0300
Subject: [PATCH 32/51] Add environment variables

---
 _pytest/config.py         |  2 +-
 doc/en/example/simple.rst |  2 ++
 doc/en/reference.rst      | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/_pytest/config.py b/_pytest/config.py
index 359cc4bc8..e8bfeccb4 100644
--- a/_pytest/config.py
+++ b/_pytest/config.py
@@ -169,7 +169,7 @@ class PytestPluginManager(PluginManager):
     Overwrites :py:class:`pluggy.PluginManager <pluggy.PluginManager>` to add pytest-specific
     functionality:
 
-    * loading plugins from the command line, ``PYTEST_PLUGIN`` env variable and
+    * loading plugins from the command line, ``PYTEST_PLUGINS`` env variable and
       ``pytest_plugins`` global variables found in plugins being loaded;
     * ``conftest.py`` loading during start-up;
     """
diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst
index 1b1cb829c..b044f43ad 100644
--- a/doc/en/example/simple.rst
+++ b/doc/en/example/simple.rst
@@ -766,6 +766,8 @@ and run it::
 You'll see that the fixture finalizers could use the precise reporting
 information.
 
+.. _pytest current test env:
+
 ``PYTEST_CURRENT_TEST`` environment variable
 --------------------------------------------
 
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 6a39f7542..3086f9be7 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -774,4 +774,43 @@ test functions and methods. Can be either a single mark or a sequence of marks.
     import pytest
     pytestmark = (pytest.mark.integration, pytest.mark.slow)
 
+PYTEST_DONT_REWRITE (module docstring)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The text ``PYTEST_DONT_REWRITE`` can be add to any **module docstring** to disable
+:ref:`assertion rewriting <assert introspection>` for that module.
+
+
+Environment Variables
+---------------------
+
+Environment variables that can be used to change pytest's behavior.
+
+PYTEST_ADDOPTS
+~~~~~~~~~~~~~~
+
+This contains a command-line (parsed by the py:mod:`shlex` module) that will be **prepended** to the command line given
+by the user, see :ref:`adding default options` for more information.
+
+PYTEST_DEBUG
+~~~~~~~~~~~~
+
+When set, pytest will print tracing and debug information.
+
+PYTEST_PLUGINS
+~~~~~~~~~~~~~~
+
+Contains comma-separated list of modules that should be loaded as plugins:
+
+.. code-block:: bash
+
+    export PYTEST_PLUGINS=mymodule.plugin,xdisst
+
+
+PYTEST_CURRENT_TEST
+~~~~~~~~~~~~~~~~~~~
+
+This is not meant to be set by users, but is set by pytest internally with the name of the current test so other
+processes can inspect it, see :ref:`pytest current test env` for more information.
+
 

From 8243900960b23e54623e2aaf2b8a3f7e529f6366 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Wed, 7 Mar 2018 20:45:41 -0300
Subject: [PATCH 33/51] Move definition of ini options to reference

---
 doc/en/customize.rst | 220 +-----------------------------------------
 doc/en/reference.rst | 224 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 225 insertions(+), 219 deletions(-)

diff --git a/doc/en/customize.rst b/doc/en/customize.rst
index 9fe094ba1..92c4e2119 100644
--- a/doc/en/customize.rst
+++ b/doc/en/customize.rst
@@ -152,222 +152,4 @@ above will show verbose output because ``-v`` overwrites ``-q``.
 Builtin configuration file options
 ----------------------------------------------
 
-Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg``
-file, usually located at the root of your repository. All options must be under a ``[pytest]`` section
-(``[tool:pytest]`` for ``setup.cfg`` files).
-
-Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be
-passed multiple times. The expected format is ``name=value``. For example::
-
-   pytest -o console_output_style=classic -o cache_dir=/tmp/mycache
-
-
-.. confval:: minversion
-
-   Specifies a minimal pytest version required for running tests.
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        minversion = 3.0  # will fail if we run with pytest-2.8
-
-.. confval:: addopts
-
-   Add the specified ``OPTS`` to the set of command line arguments as if they
-   had been specified by the user. Example: if you have this ini file content:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info
-
-   issuing ``pytest test_hello.py`` actually means::
-
-        pytest --maxfail=2 -rf test_hello.py
-
-   Default is to add no options.
-
-.. confval:: norecursedirs
-
-   Set the directory basename patterns to avoid when recursing
-   for test discovery.  The individual (fnmatch-style) patterns are
-   applied to the basename of a directory to decide if to recurse into it.
-   Pattern matching characters::
-
-        *       matches everything
-        ?       matches any single character
-        [seq]   matches any character in seq
-        [!seq]  matches any char not in seq
-
-   Default patterns are ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``.
-   Setting a ``norecursedirs`` replaces the default.  Here is an example of
-   how to avoid certain directories:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        norecursedirs = .svn _build tmp*
-
-   This would tell ``pytest`` to not look into typical subversion or
-   sphinx-build directories or into any ``tmp`` prefixed directory.  
-   
-   Additionally, ``pytest`` will attempt to intelligently identify and ignore a
-   virtualenv by the presence of an activation script.  Any directory deemed to
-   be the root of a virtual environment will not be considered during test
-   collection unless ``‑‑collect‑in‑virtualenv`` is given.  Note also that
-   ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if
-   you intend to run tests in a virtualenv with a base directory that matches
-   ``'.*'`` you *must* override ``norecursedirs`` in addition to using the
-   ``‑‑collect‑in‑virtualenv`` flag.
-
-.. confval:: testpaths
-
-   .. versionadded:: 2.8
-
-   Sets list of directories that should be searched for tests when
-   no specific directories, files or test ids are given in the command line when
-   executing pytest from the :ref:`rootdir <rootdir>` directory.
-   Useful when all project tests are in a known location to speed up
-   test collection and to avoid picking up undesired tests by accident.
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        testpaths = testing doc
-
-   This tells pytest to only look for tests in ``testing`` and ``doc``
-   directories when executing from the root directory.
-
-.. confval:: python_files
-
-   One or more Glob-style file patterns determining which python files
-   are considered as test modules. By default, pytest will consider
-   any file matching with ``test_*.py`` and ``*_test.py`` globs as a test
-   module.
-
-.. confval:: python_classes
-
-   One or more name prefixes or glob-style patterns determining which classes
-   are considered for test collection. By default, pytest will consider any
-   class prefixed with ``Test`` as a test collection.  Here is an example of how
-   to collect tests from classes that end in ``Suite``:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        python_classes = *Suite
-
-   Note that ``unittest.TestCase`` derived classes are always collected
-   regardless of this option, as ``unittest``'s own collection framework is used
-   to collect those tests.
-
-.. confval:: python_functions
-
-   One or more name prefixes or glob-patterns determining which test functions
-   and methods are considered tests. By default, pytest will consider any
-   function prefixed with ``test`` as a test.  Here is an example of how
-   to collect test functions and methods that end in ``_test``:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        python_functions = *_test
-
-   Note that this has no effect on methods that live on a ``unittest
-   .TestCase`` derived class, as ``unittest``'s own collection framework is used
-   to collect those tests.
-
-   See :ref:`change naming conventions` for more detailed examples.
-
-.. confval:: doctest_optionflags
-
-   One or more doctest flag names from the standard ``doctest`` module.
-   :doc:`See how pytest handles doctests <doctest>`.
-
-.. confval:: confcutdir
-
-   Sets a directory where search upwards for ``conftest.py`` files stops.
-   By default, pytest will stop searching for ``conftest.py`` files upwards
-   from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any,
-   or up to the file-system root.
-
-
-.. confval:: filterwarnings
-
-   .. versionadded:: 3.1
-
-   Sets a list of filters and actions that should be taken for matched
-   warnings. By default all warnings emitted during the test session
-   will be displayed in a summary at the end of the test session.
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        filterwarnings =
-            error
-            ignore::DeprecationWarning
-
-   This tells pytest to ignore deprecation warnings and turn all other warnings
-   into errors. For more information please refer to :ref:`warnings`.
-
-.. confval:: cache_dir
-
-   .. versionadded:: 3.2
-
-   Sets a directory where stores content of cache plugin. Default directory is
-   ``.cache`` which is created in :ref:`rootdir <rootdir>`. Directory may be
-   relative or absolute path. If setting relative path, then directory is created
-   relative to :ref:`rootdir <rootdir>`. Additionally path may contain environment
-   variables, that will be expanded. For more information about cache plugin
-   please refer to :ref:`cache_provider`.
-
-
-.. confval:: console_output_style
-
-   .. versionadded:: 3.3
-
-   Sets the console output style while running tests:
-
-   * ``classic``: classic pytest output.
-   * ``progress``: like classic pytest output, but with a progress indicator.
-
-   The default is ``progress``, but you can fallback to ``classic`` if you prefer or
-   the new mode is causing unexpected problems:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        console_output_style = classic
-
-
-.. confval:: empty_parameter_set_mark
-
-    .. versionadded:: 3.4
-
-    Allows to pick the action for empty parametersets in parameterization
-
-    * ``skip`` skips tests with a empty parameterset (default)
-    * ``xfail`` marks tests with a empty parameterset as xfail(run=False)
-
-    .. code-block:: ini
-
-      # content of pytest.ini
-      [pytest]
-      empty_parameter_set_mark = xfail
-
-    .. note::
-
-      The default value of this option is planned to change to ``xfail`` in future releases
-      as this is considered less error prone, see `#3155`_ for more details.
-
-
-
-.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155
+For the full list of options consult the :ref:`reference documentation <ini options ref>`.
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 3086f9be7..a027d5c9e 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -814,3 +814,227 @@ This is not meant to be set by users, but is set by pytest internally with the n
 processes can inspect it, see :ref:`pytest current test env` for more information.
 
 
+.. _`ini options ref`:
+
+Configuration Options
+---------------------
+
+Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg``
+file, usually located at the root of your repository. All options must be under a ``[pytest]`` section
+(``[tool:pytest]`` for ``setup.cfg`` files).
+
+Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be
+passed multiple times. The expected format is ``name=value``. For example::
+
+   pytest -o console_output_style=classic -o cache_dir=/tmp/mycache
+
+
+.. confval:: minversion
+
+   Specifies a minimal pytest version required for running tests.
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        minversion = 3.0  # will fail if we run with pytest-2.8
+
+.. confval:: addopts
+
+   Add the specified ``OPTS`` to the set of command line arguments as if they
+   had been specified by the user. Example: if you have this ini file content:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info
+
+   issuing ``pytest test_hello.py`` actually means::
+
+        pytest --maxfail=2 -rf test_hello.py
+
+   Default is to add no options.
+
+.. confval:: norecursedirs
+
+   Set the directory basename patterns to avoid when recursing
+   for test discovery.  The individual (fnmatch-style) patterns are
+   applied to the basename of a directory to decide if to recurse into it.
+   Pattern matching characters::
+
+        *       matches everything
+        ?       matches any single character
+        [seq]   matches any character in seq
+        [!seq]  matches any char not in seq
+
+   Default patterns are ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``.
+   Setting a ``norecursedirs`` replaces the default.  Here is an example of
+   how to avoid certain directories:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        norecursedirs = .svn _build tmp*
+
+   This would tell ``pytest`` to not look into typical subversion or
+   sphinx-build directories or into any ``tmp`` prefixed directory.
+
+   Additionally, ``pytest`` will attempt to intelligently identify and ignore a
+   virtualenv by the presence of an activation script.  Any directory deemed to
+   be the root of a virtual environment will not be considered during test
+   collection unless ``‑‑collect‑in‑virtualenv`` is given.  Note also that
+   ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if
+   you intend to run tests in a virtualenv with a base directory that matches
+   ``'.*'`` you *must* override ``norecursedirs`` in addition to using the
+   ``‑‑collect‑in‑virtualenv`` flag.
+
+.. confval:: testpaths
+
+   .. versionadded:: 2.8
+
+   Sets list of directories that should be searched for tests when
+   no specific directories, files or test ids are given in the command line when
+   executing pytest from the :ref:`rootdir <rootdir>` directory.
+   Useful when all project tests are in a known location to speed up
+   test collection and to avoid picking up undesired tests by accident.
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        testpaths = testing doc
+
+   This tells pytest to only look for tests in ``testing`` and ``doc``
+   directories when executing from the root directory.
+
+.. confval:: python_files
+
+   One or more Glob-style file patterns determining which python files
+   are considered as test modules. By default, pytest will consider
+   any file matching with ``test_*.py`` and ``*_test.py`` globs as a test
+   module.
+
+.. confval:: python_classes
+
+   One or more name prefixes or glob-style patterns determining which classes
+   are considered for test collection. By default, pytest will consider any
+   class prefixed with ``Test`` as a test collection.  Here is an example of how
+   to collect tests from classes that end in ``Suite``:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        python_classes = *Suite
+
+   Note that ``unittest.TestCase`` derived classes are always collected
+   regardless of this option, as ``unittest``'s own collection framework is used
+   to collect those tests.
+
+.. confval:: python_functions
+
+   One or more name prefixes or glob-patterns determining which test functions
+   and methods are considered tests. By default, pytest will consider any
+   function prefixed with ``test`` as a test.  Here is an example of how
+   to collect test functions and methods that end in ``_test``:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        python_functions = *_test
+
+   Note that this has no effect on methods that live on a ``unittest
+   .TestCase`` derived class, as ``unittest``'s own collection framework is used
+   to collect those tests.
+
+   See :ref:`change naming conventions` for more detailed examples.
+
+.. confval:: doctest_optionflags
+
+   One or more doctest flag names from the standard ``doctest`` module.
+   :doc:`See how pytest handles doctests <doctest>`.
+
+.. confval:: confcutdir
+
+   Sets a directory where search upwards for ``conftest.py`` files stops.
+   By default, pytest will stop searching for ``conftest.py`` files upwards
+   from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any,
+   or up to the file-system root.
+
+
+.. confval:: filterwarnings
+
+   .. versionadded:: 3.1
+
+   Sets a list of filters and actions that should be taken for matched
+   warnings. By default all warnings emitted during the test session
+   will be displayed in a summary at the end of the test session.
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        filterwarnings =
+            error
+            ignore::DeprecationWarning
+
+   This tells pytest to ignore deprecation warnings and turn all other warnings
+   into errors. For more information please refer to :ref:`warnings`.
+
+.. confval:: cache_dir
+
+   .. versionadded:: 3.2
+
+   Sets a directory where stores content of cache plugin. Default directory is
+   ``.cache`` which is created in :ref:`rootdir <rootdir>`. Directory may be
+   relative or absolute path. If setting relative path, then directory is created
+   relative to :ref:`rootdir <rootdir>`. Additionally path may contain environment
+   variables, that will be expanded. For more information about cache plugin
+   please refer to :ref:`cache_provider`.
+
+
+.. confval:: console_output_style
+
+   .. versionadded:: 3.3
+
+   Sets the console output style while running tests:
+
+   * ``classic``: classic pytest output.
+   * ``progress``: like classic pytest output, but with a progress indicator.
+
+   The default is ``progress``, but you can fallback to ``classic`` if you prefer or
+   the new mode is causing unexpected problems:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        console_output_style = classic
+
+
+.. confval:: empty_parameter_set_mark
+
+    .. versionadded:: 3.4
+
+    Allows to pick the action for empty parametersets in parameterization
+
+    * ``skip`` skips tests with a empty parameterset (default)
+    * ``xfail`` marks tests with a empty parameterset as xfail(run=False)
+
+    .. code-block:: ini
+
+      # content of pytest.ini
+      [pytest]
+      empty_parameter_set_mark = xfail
+
+    .. note::
+
+      The default value of this option is planned to change to ``xfail`` in future releases
+      as this is considered less error prone, see `#3155`_ for more details.
+
+
+
+.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155

From e71d907d3471e5cc10ab7de9a07f1706a30aca29 Mon Sep 17 00:00:00 2001
From: Julien Palard <julien@palard.fr>
Date: Mon, 12 Mar 2018 15:19:26 +0100
Subject: [PATCH 34/51] Typo in example, os.getcwd does not take any parameter.

---
 _pytest/monkeypatch.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_pytest/monkeypatch.py b/_pytest/monkeypatch.py
index c402213e8..c82ffd053 100644
--- a/_pytest/monkeypatch.py
+++ b/_pytest/monkeypatch.py
@@ -113,7 +113,7 @@ class MonkeyPatch(object):
         For convenience you can specify a string as ``target`` which
         will be interpreted as a dotted import path, with the last part
         being the attribute name.  Example:
-        ``monkeypatch.setattr("os.getcwd", lambda x: "/")``
+        ``monkeypatch.setattr("os.getcwd", lambda: "/")``
         would set the ``getcwd`` function of the ``os`` module.
 
         The ``raising`` value determines if the setattr should fail

From 61b8ea8656c6cc3577c9cd5178a105a450cb0252 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 19:27:17 -0300
Subject: [PATCH 35/51] Add doctest_encoding and junit_suite_name ini options

---
 doc/en/reference.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index a027d5c9e..25e7fcef0 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -957,6 +957,13 @@ passed multiple times. The expected format is ``name=value``. For example::
    One or more doctest flag names from the standard ``doctest`` module.
    :doc:`See how pytest handles doctests <doctest>`.
 
+.. confval:: doctest_encoding
+
+   .. versionadded:: 3.1
+
+   Default encoding to use to decode text files with docstrings.
+   :doc:`See how pytest handles doctests <doctest>`.
+
 .. confval:: confcutdir
 
    Sets a directory where search upwards for ``conftest.py`` files stops.
@@ -1036,5 +1043,17 @@ passed multiple times. The expected format is ``name=value``. For example::
       as this is considered less error prone, see `#3155`_ for more details.
 
 
+.. confval:: junit_suite_name
+
+    .. versionadded:: 3.1
+
+    To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file:
+
+    .. code-block:: ini
+
+        [pytest]
+        junit_suite_name = my_suite
+
+
 
 .. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155

From 68375513f300e51c4ee97172a4dc4728e89d898a Mon Sep 17 00:00:00 2001
From: Kostis Anagnostopoulos <ankostis@gmail.com>
Date: Tue, 13 Mar 2018 00:28:47 +0200
Subject: [PATCH 36/51] Add TC to demonstrate #3297 that caplog.clear() does
 not clean text

---
 testing/logging/test_fixture.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/testing/logging/test_fixture.py b/testing/logging/test_fixture.py
index 204472c80..24576719d 100644
--- a/testing/logging/test_fixture.py
+++ b/testing/logging/test_fixture.py
@@ -95,8 +95,10 @@ def test_clear(caplog):
     caplog.set_level(logging.INFO)
     logger.info(u'bū')
     assert len(caplog.records)
+    assert caplog.text
     caplog.clear()
     assert not len(caplog.records)
+    assert not caplog.text
 
 
 @pytest.fixture

From 3198596f8adf03c88cdad16c360c066d3200fbbb Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 19:33:34 -0300
Subject: [PATCH 37/51] Sort ini options

---
 doc/en/reference.rst | 268 ++++++++++++++++++++++---------------------
 1 file changed, 138 insertions(+), 130 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 25e7fcef0..f97233524 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -829,16 +829,6 @@ passed multiple times. The expected format is ``name=value``. For example::
    pytest -o console_output_style=classic -o cache_dir=/tmp/mycache
 
 
-.. confval:: minversion
-
-   Specifies a minimal pytest version required for running tests.
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        minversion = 3.0  # will fail if we run with pytest-2.8
-
 .. confval:: addopts
 
    Add the specified ``OPTS`` to the set of command line arguments as if they
@@ -856,6 +846,125 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    Default is to add no options.
 
+
+.. confval:: cache_dir
+
+   .. versionadded:: 3.2
+
+   Sets a directory where stores content of cache plugin. Default directory is
+   ``.cache`` which is created in :ref:`rootdir <rootdir>`. Directory may be
+   relative or absolute path. If setting relative path, then directory is created
+   relative to :ref:`rootdir <rootdir>`. Additionally path may contain environment
+   variables, that will be expanded. For more information about cache plugin
+   please refer to :ref:`cache_provider`.
+
+
+.. confval:: confcutdir
+
+   Sets a directory where search upwards for ``conftest.py`` files stops.
+   By default, pytest will stop searching for ``conftest.py`` files upwards
+   from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any,
+   or up to the file-system root.
+
+
+.. confval:: console_output_style
+
+   .. versionadded:: 3.3
+
+   Sets the console output style while running tests:
+
+   * ``classic``: classic pytest output.
+   * ``progress``: like classic pytest output, but with a progress indicator.
+
+   The default is ``progress``, but you can fallback to ``classic`` if you prefer or
+   the new mode is causing unexpected problems:
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        console_output_style = classic
+
+
+.. confval:: doctest_encoding
+
+   .. versionadded:: 3.1
+
+   Default encoding to use to decode text files with docstrings.
+   :doc:`See how pytest handles doctests <doctest>`.
+
+
+.. confval:: doctest_optionflags
+
+   One or more doctest flag names from the standard ``doctest`` module.
+   :doc:`See how pytest handles doctests <doctest>`.
+
+
+.. confval:: empty_parameter_set_mark
+
+    .. versionadded:: 3.4
+
+    Allows to pick the action for empty parametersets in parameterization
+
+    * ``skip`` skips tests with a empty parameterset (default)
+    * ``xfail`` marks tests with a empty parameterset as xfail(run=False)
+
+    .. code-block:: ini
+
+      # content of pytest.ini
+      [pytest]
+      empty_parameter_set_mark = xfail
+
+    .. note::
+
+      The default value of this option is planned to change to ``xfail`` in future releases
+      as this is considered less error prone, see `#3155 <https://github.com/pytest-dev/pytest/issues/3155>`_
+      for more details.
+
+
+.. confval:: filterwarnings
+
+   .. versionadded:: 3.1
+
+   Sets a list of filters and actions that should be taken for matched
+   warnings. By default all warnings emitted during the test session
+   will be displayed in a summary at the end of the test session.
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        filterwarnings =
+            error
+            ignore::DeprecationWarning
+
+   This tells pytest to ignore deprecation warnings and turn all other warnings
+   into errors. For more information please refer to :ref:`warnings`.
+
+
+.. confval:: junit_suite_name
+
+    .. versionadded:: 3.1
+
+    To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file:
+
+    .. code-block:: ini
+
+        [pytest]
+        junit_suite_name = my_suite
+
+
+.. confval:: minversion
+
+   Specifies a minimal pytest version required for running tests.
+
+   .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        minversion = 3.0  # will fail if we run with pytest-2.8
+
+
 .. confval:: norecursedirs
 
    Set the directory basename patterns to avoid when recursing
@@ -890,31 +999,6 @@ passed multiple times. The expected format is ``name=value``. For example::
    ``'.*'`` you *must* override ``norecursedirs`` in addition to using the
    ``‑‑collect‑in‑virtualenv`` flag.
 
-.. confval:: testpaths
-
-   .. versionadded:: 2.8
-
-   Sets list of directories that should be searched for tests when
-   no specific directories, files or test ids are given in the command line when
-   executing pytest from the :ref:`rootdir <rootdir>` directory.
-   Useful when all project tests are in a known location to speed up
-   test collection and to avoid picking up undesired tests by accident.
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        testpaths = testing doc
-
-   This tells pytest to only look for tests in ``testing`` and ``doc``
-   directories when executing from the root directory.
-
-.. confval:: python_files
-
-   One or more Glob-style file patterns determining which python files
-   are considered as test modules. By default, pytest will consider
-   any file matching with ``test_*.py`` and ``*_test.py`` globs as a test
-   module.
 
 .. confval:: python_classes
 
@@ -933,6 +1017,15 @@ passed multiple times. The expected format is ``name=value``. For example::
    regardless of this option, as ``unittest``'s own collection framework is used
    to collect those tests.
 
+
+.. confval:: python_files
+
+   One or more Glob-style file patterns determining which python files
+   are considered as test modules. By default, pytest will consider
+   any file matching with ``test_*.py`` and ``*_test.py`` globs as a test
+   module.
+
+
 .. confval:: python_functions
 
    One or more name prefixes or glob-patterns determining which test functions
@@ -952,108 +1045,23 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    See :ref:`change naming conventions` for more detailed examples.
 
-.. confval:: doctest_optionflags
 
-   One or more doctest flag names from the standard ``doctest`` module.
-   :doc:`See how pytest handles doctests <doctest>`.
+.. confval:: testpaths
 
-.. confval:: doctest_encoding
+   .. versionadded:: 2.8
 
-   .. versionadded:: 3.1
-
-   Default encoding to use to decode text files with docstrings.
-   :doc:`See how pytest handles doctests <doctest>`.
-
-.. confval:: confcutdir
-
-   Sets a directory where search upwards for ``conftest.py`` files stops.
-   By default, pytest will stop searching for ``conftest.py`` files upwards
-   from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any,
-   or up to the file-system root.
-
-
-.. confval:: filterwarnings
-
-   .. versionadded:: 3.1
-
-   Sets a list of filters and actions that should be taken for matched
-   warnings. By default all warnings emitted during the test session
-   will be displayed in a summary at the end of the test session.
+   Sets list of directories that should be searched for tests when
+   no specific directories, files or test ids are given in the command line when
+   executing pytest from the :ref:`rootdir <rootdir>` directory.
+   Useful when all project tests are in a known location to speed up
+   test collection and to avoid picking up undesired tests by accident.
 
    .. code-block:: ini
 
         # content of pytest.ini
         [pytest]
-        filterwarnings =
-            error
-            ignore::DeprecationWarning
+        testpaths = testing doc
 
-   This tells pytest to ignore deprecation warnings and turn all other warnings
-   into errors. For more information please refer to :ref:`warnings`.
+   This tells pytest to only look for tests in ``testing`` and ``doc``
+   directories when executing from the root directory.
 
-.. confval:: cache_dir
-
-   .. versionadded:: 3.2
-
-   Sets a directory where stores content of cache plugin. Default directory is
-   ``.cache`` which is created in :ref:`rootdir <rootdir>`. Directory may be
-   relative or absolute path. If setting relative path, then directory is created
-   relative to :ref:`rootdir <rootdir>`. Additionally path may contain environment
-   variables, that will be expanded. For more information about cache plugin
-   please refer to :ref:`cache_provider`.
-
-
-.. confval:: console_output_style
-
-   .. versionadded:: 3.3
-
-   Sets the console output style while running tests:
-
-   * ``classic``: classic pytest output.
-   * ``progress``: like classic pytest output, but with a progress indicator.
-
-   The default is ``progress``, but you can fallback to ``classic`` if you prefer or
-   the new mode is causing unexpected problems:
-
-   .. code-block:: ini
-
-        # content of pytest.ini
-        [pytest]
-        console_output_style = classic
-
-
-.. confval:: empty_parameter_set_mark
-
-    .. versionadded:: 3.4
-
-    Allows to pick the action for empty parametersets in parameterization
-
-    * ``skip`` skips tests with a empty parameterset (default)
-    * ``xfail`` marks tests with a empty parameterset as xfail(run=False)
-
-    .. code-block:: ini
-
-      # content of pytest.ini
-      [pytest]
-      empty_parameter_set_mark = xfail
-
-    .. note::
-
-      The default value of this option is planned to change to ``xfail`` in future releases
-      as this is considered less error prone, see `#3155`_ for more details.
-
-
-.. confval:: junit_suite_name
-
-    .. versionadded:: 3.1
-
-    To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file:
-
-    .. code-block:: ini
-
-        [pytest]
-        junit_suite_name = my_suite
-
-
-
-.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155

From 5e92644f94cd3432aa1de86b905ce23748526857 Mon Sep 17 00:00:00 2001
From: Thomas Hisch <t.hisch@gmail.com>
Date: Mon, 12 Mar 2018 23:11:45 +0100
Subject: [PATCH 38/51] Properly reset LogCaptureHandler in caplog

Closes #3297
---
 _pytest/logging.py | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/_pytest/logging.py b/_pytest/logging.py
index 6d9274d1a..c920659a5 100644
--- a/_pytest/logging.py
+++ b/_pytest/logging.py
@@ -176,6 +176,10 @@ class LogCaptureHandler(logging.StreamHandler):
         self.records.append(record)
         logging.StreamHandler.emit(self, record)
 
+    def reset(self):
+        self.records = []
+        self.stream = py.io.TextIO()
+
 
 class LogCaptureFixture(object):
     """Provides access and control of log capturing."""
@@ -197,6 +201,9 @@ class LogCaptureFixture(object):
 
     @property
     def handler(self):
+        """
+        :rtype: LogCaptureHandler
+        """
         return self._item.catch_log_handler
 
     def get_records(self, when):
@@ -239,8 +246,8 @@ class LogCaptureFixture(object):
         return [(r.name, r.levelno, r.getMessage()) for r in self.records]
 
     def clear(self):
-        """Reset the list of log records."""
-        self.handler.records = []
+        """Reset the list of log records and the captured log text."""
+        self.handler.reset()
 
     def set_level(self, level, logger=None):
         """Sets the level for capturing of logs. The level will be restored to its previous value at the end of
@@ -285,6 +292,8 @@ def caplog(request):
     * caplog.text()          -> string containing formatted log output
     * caplog.records()       -> list of logging.LogRecord instances
     * caplog.record_tuples() -> list of (logger_name, level, message) tuples
+    * caplog.clear()         -> clear captured records and formatted log output
+                                string
     """
     result = LogCaptureFixture(request.node)
     yield result

From 8629ef6a787d906bdfee0416c1ecc73e2660085d Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 19:43:04 -0300
Subject: [PATCH 39/51] Add missing ini options: markers, usefixtures and
 xfail_strict

---
 doc/en/reference.rst | 37 +++++++++++++++++++++++++++++++++++++
 doc/en/skipping.rst  |  3 +++
 2 files changed, 40 insertions(+)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index f97233524..796c6ffcc 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -954,6 +954,18 @@ passed multiple times. The expected format is ``name=value``. For example::
         junit_suite_name = my_suite
 
 
+.. confval:: markers
+
+    List of markers that are allowed in test functions, enforced when ``--strict`` command-line argument is used.
+    You can use a marker name per line, indented from the option name.
+
+    .. code-block:: ini
+
+        [pytest]
+        markers =
+            slow
+            serial
+
 .. confval:: minversion
 
    Specifies a minimal pytest version required for running tests.
@@ -1065,3 +1077,28 @@ passed multiple times. The expected format is ``name=value``. For example::
    This tells pytest to only look for tests in ``testing`` and ``doc``
    directories when executing from the root directory.
 
+
+.. confval:: usefixtures
+
+    List of fixtures that will be applied to all test functions; this is semantically the same to apply
+    the ``@pytest.mark.usefixtures`` marker to all test functions.
+
+
+    .. code-block:: ini
+
+        [pytest]
+        usefixtures =
+            clean_db
+
+
+.. confval:: xfail_strict
+
+    If set to ``True``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the
+    test suite.
+    For more information, see :ref:`xfail strict tutorial`.
+
+
+    .. code-block:: ini
+
+        [pytest]
+        xfail_strict = True
diff --git a/doc/en/skipping.rst b/doc/en/skipping.rst
index 195674199..9bac02c8c 100644
--- a/doc/en/skipping.rst
+++ b/doc/en/skipping.rst
@@ -238,6 +238,9 @@ internally by raising a known exception.
 
 **Reference**: :ref:`pytest.mark.xfail ref`
 
+
+.. _`xfail strict tutorial`:
+
 ``strict`` parameter
 ~~~~~~~~~~~~~~~~~~~~
 

From 2e347643a3d0bea7d94fdb630a90b4f489eee051 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 20:09:05 -0300
Subject: [PATCH 40/51] Add ini options for logging

---
 CHANGELOG.rst        |   2 +-
 doc/en/reference.rst | 155 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 040c91118..41afe60ab 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -377,7 +377,7 @@ Features
 - Match ``warns`` signature to ``raises`` by adding ``match`` keyword. (`#2708
   <https://github.com/pytest-dev/pytest/issues/2708>`_)
 
-- Pytest now captures and displays output from the standard `logging` module.
+- Pytest now captures and displays output from the standard :py:mod:`logging` module.
   The user can control the logging level to be captured by specifying options
   in ``pytest.ini``, the command line and also during individual tests using
   markers. Also, a ``caplog`` fixture is available that enables users to test
diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 796c6ffcc..4cb961fe4 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -954,6 +954,161 @@ passed multiple times. The expected format is ``name=value``. For example::
         junit_suite_name = my_suite
 
 
+.. confval:: log_cli_date_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for live logging.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_cli_date_format = %Y-%m-%d %H:%M:%S
+
+    For more information, see :ref:`live_logs`.
+
+.. confval:: log_cli_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:mod:`logging`-compatible string used to format live logging messages.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_cli_format = %(asctime)s %(levelname)s %(message)s
+
+    For more information, see :ref:`live_logs`.
+
+
+.. confval:: log_cli_level
+
+    .. versionadded:: 3.3
+
+    Sets the minimum log message level that should be captured for live logging. The integer value or
+    the names of the levels can be used.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_cli_level = INFO 
+
+    For more information, see :ref:`live_logs`.
+
+
+.. confval:: log_date_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for logging capture.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_date_format = %Y-%m-%d %H:%M:%S
+
+    For more information, see :ref:`logging`.
+
+
+.. confval:: log_file
+
+    .. versionadded:: 3.3
+
+    Sets a file name relative to the ``pytest.ini`` file where log messages should be written to, in addition
+    to the other logging facilities that are active.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_file = logs/pytest-logs.txt
+
+    For more information, see :ref:`logging`.
+
+
+.. confval:: log_file_date_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_file_date_format = %Y-%m-%d %H:%M:%S
+
+    For more information, see :ref:`logging`.
+
+.. confval:: log_file_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_file_format = %(asctime)s %(levelname)s %(message)s
+
+    For more information, see :ref:`logging`.
+
+.. confval:: log_file_level
+
+    .. versionadded:: 3.3
+
+    Sets the minimum log message level that should be captured for the logging file. The integer value or
+    the names of the levels can be used.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_file_level = INFO
+
+    For more information, see :ref:`logging`.
+
+
+.. confval:: log_format
+
+    .. versionadded:: 3.3
+
+    Sets a :py:mod:`logging`-compatible string used to format captured logging messages.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_format = %(asctime)s %(levelname)s %(message)s
+
+    For more information, see :ref:`logging`.
+
+
+.. confval:: log_level
+
+    .. versionadded:: 3.3
+
+    Sets the minimum log message level that should be captured for logging capture. The integer value or
+    the names of the levels can be used.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_level = INFO
+
+    For more information, see :ref:`logging`.
+
+
+.. confval:: log_print
+
+    .. versionadded:: 3.3
+
+    If set to ``False``, will disable displaying captured logging messages for failed tests.
+
+    .. code-block:: ini
+
+        [pytest]
+        log_print = False
+
+    For more information, see :ref:`logging`.
+
+
 .. confval:: markers
 
     List of markers that are allowed in test functions, enforced when ``--strict`` command-line argument is used.

From 4459aa3d8b827796f4046efb7abd283f18a9af3a Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 20:09:31 -0300
Subject: [PATCH 41/51] Remove redundant "# content of pytest.ini" headers from
 examples

---
 doc/en/reference.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/doc/en/reference.rst b/doc/en/reference.rst
index 4cb961fe4..f28b8166b 100644
--- a/doc/en/reference.rst
+++ b/doc/en/reference.rst
@@ -1150,7 +1150,6 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    .. code-block:: ini
 
-        # content of pytest.ini
         [pytest]
         norecursedirs = .svn _build tmp*
 
@@ -1176,7 +1175,6 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    .. code-block:: ini
 
-        # content of pytest.ini
         [pytest]
         python_classes = *Suite
 
@@ -1202,7 +1200,6 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    .. code-block:: ini
 
-        # content of pytest.ini
         [pytest]
         python_functions = *_test
 
@@ -1225,7 +1222,6 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    .. code-block:: ini
 
-        # content of pytest.ini
         [pytest]
         testpaths = testing doc
 

From 02bec7a3bb96625042ec00adfe45e71d454f10f1 Mon Sep 17 00:00:00 2001
From: Kostis Anagnostopoulos <ankostis@gmail.com>
Date: Tue, 13 Mar 2018 00:52:02 +0200
Subject: [PATCH 42/51] Add changelog & myself (ankostis) to authors

---
 AUTHORS                   | 1 +
 changelog/3297.bugfix.rst | 2 ++
 2 files changed, 3 insertions(+)
 create mode 100644 changelog/3297.bugfix.rst

diff --git a/AUTHORS b/AUTHORS
index 3a564606c..25c4384cd 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -105,6 +105,7 @@ Kale Kundert
 Katarzyna Jachim
 Kevin Cox
 Kodi B. Arfer
+Kostis Anagnostopoulos
 Lawrence Mitchell
 Lee Kamentsky
 Lev Maximov
diff --git a/changelog/3297.bugfix.rst b/changelog/3297.bugfix.rst
new file mode 100644
index 000000000..f3cbc2c9c
--- /dev/null
+++ b/changelog/3297.bugfix.rst
@@ -0,0 +1,2 @@
+Fixed ``clear()`` method on ``caplog`` fixture which cleared ``records``,
+but not the ``text`` property.
\ No newline at end of file

From 51c0256cd4f069449651b82a35a98e8f54c73b4b Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Mon, 12 Mar 2018 20:57:51 -0300
Subject: [PATCH 43/51] Remove :py:mod: ref from changelog: fails our linting
 check

---
 CHANGELOG.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 41afe60ab..a0e8897df 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,4 +1,4 @@
-.. 
+..
     You should *NOT* be adding new change log entries to this file, this
     file is managed by towncrier. You *may* edit previous change logs to
     fix problems like typo corrections or such.
@@ -377,7 +377,7 @@ Features
 - Match ``warns`` signature to ``raises`` by adding ``match`` keyword. (`#2708
   <https://github.com/pytest-dev/pytest/issues/2708>`_)
 
-- Pytest now captures and displays output from the standard :py:mod:`logging` module.
+- Pytest now captures and displays output from the standard ``logging`` module.
   The user can control the logging level to be captured by specifying options
   in ``pytest.ini``, the command line and also during individual tests using
   markers. Also, a ``caplog`` fixture is available that enables users to test

From 9517c3a2aa2418b226ee7ef0675791d96aa23b2e Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 13 Mar 2018 17:41:26 -0300
Subject: [PATCH 44/51] Suppress ``IOError`` when closing the temporary file
 used for capturing streams in Python 2.7.

Fix #2370
---
 _pytest/capture.py        | 15 +++++++++++++--
 changelog/2370.bugfix.rst |  1 +
 testing/test_capture.py   | 24 ++++++++++++++++++++++++
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 changelog/2370.bugfix.rst

diff --git a/_pytest/capture.py b/_pytest/capture.py
index 36658acce..fc429e073 100644
--- a/_pytest/capture.py
+++ b/_pytest/capture.py
@@ -476,7 +476,7 @@ class FDCaptureBinary(object):
         os.dup2(targetfd_save, self.targetfd)
         os.close(targetfd_save)
         self.syscapture.done()
-        self.tmpfile.close()
+        _attempt_to_close_capture_file(self.tmpfile)
 
     def suspend(self):
         self.syscapture.suspend()
@@ -530,7 +530,7 @@ class SysCapture(object):
     def done(self):
         setattr(sys, self.name, self._old)
         del self._old
-        self.tmpfile.close()
+        _attempt_to_close_capture_file(self.tmpfile)
 
     def suspend(self):
         setattr(sys, self.name, self._old)
@@ -681,3 +681,14 @@ def _py36_windowsconsoleio_workaround(stream):
     sys.__stdin__ = sys.stdin = _reopen_stdio(sys.stdin, 'rb')
     sys.__stdout__ = sys.stdout = _reopen_stdio(sys.stdout, 'wb')
     sys.__stderr__ = sys.stderr = _reopen_stdio(sys.stderr, 'wb')
+
+
+def _attempt_to_close_capture_file(f):
+    """Suppress IOError when closing the temporary file used for capturing streams in py27 (#2370)"""
+    if six.PY2:
+        try:
+            f.close()
+        except IOError:
+            pass
+    else:
+        f.close()
diff --git a/changelog/2370.bugfix.rst b/changelog/2370.bugfix.rst
new file mode 100644
index 000000000..937acb471
--- /dev/null
+++ b/changelog/2370.bugfix.rst
@@ -0,0 +1 @@
+Suppress ``IOError`` when closing the temporary file used for capturing streams in Python 2.7.
diff --git a/testing/test_capture.py b/testing/test_capture.py
index 69afa0f9c..4f9028fca 100644
--- a/testing/test_capture.py
+++ b/testing/test_capture.py
@@ -1265,6 +1265,30 @@ def test_dontreadfrominput_has_encoding(testdir):
     reprec.assertoutcome(passed=1)
 
 
+def test_crash_on_closing_tmpfile_py27(testdir):
+    testdir.makepyfile('''
+        from __future__ import print_function
+        import time
+        import threading
+        import sys
+
+        def spam():
+            f = sys.stderr
+            while True:
+                print('.', end='', file=f)
+
+        def test_silly():
+            t = threading.Thread(target=spam)
+            t.daemon = True
+            t.start()
+            time.sleep(0.5)
+
+    ''')
+    result = testdir.runpytest_subprocess()
+    assert result.ret == 0
+    assert 'IOError' not in result.stdout.str()
+
+
 def test_pickling_and_unpickling_encoded_file():
     # See https://bitbucket.org/pytest-dev/pytest/pull-request/194
     # pickle.loads() raises infinite recursion if

From 7e53f9432cc8329ffba85728b676d94ade96d234 Mon Sep 17 00:00:00 2001
From: Tareq Alayan <tareq.alayan@gmail.com>
Date: Wed, 14 Mar 2018 13:51:45 +0200
Subject: [PATCH 45/51] issue #3308: fix example in documentation

https://github.com/pytest-dev/pytest/issues/3308
---
 changelog/3308.trivial.rst | 1 +
 doc/en/usage.rst           | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 100644 changelog/3308.trivial.rst

diff --git a/changelog/3308.trivial.rst b/changelog/3308.trivial.rst
new file mode 100644
index 000000000..693384836
--- /dev/null
+++ b/changelog/3308.trivial.rst
@@ -0,0 +1 @@
+Fix a python example when calling a fixture in doc/en/usage.rst
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index abd8bac2b..ffb380b78 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -337,7 +337,7 @@ to all testcases you can use ``LogXML.add_global_properties``
         my_junit.add_global_property('ARCH', 'PPC')
         my_junit.add_global_property('STORAGE_TYPE', 'CEPH')
 
-    @pytest.mark.usefixtures(log_global_env_facts)
+    @pytest.mark.usefixtures(log_global_env_facts.__name__)
     def start_and_prepare_env():
         pass
 

From 3c3fc3bb9dcd4ba9902e59c8160163d0c962dbe1 Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Thu, 15 Mar 2018 21:25:50 -0400
Subject: [PATCH 46/51] Add test capturing new expectation. Ref #3314.

---
 testing/test_capture.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/testing/test_capture.py b/testing/test_capture.py
index 4f9028fca..7fccc055d 100644
--- a/testing/test_capture.py
+++ b/testing/test_capture.py
@@ -751,7 +751,8 @@ def test_dontreadfrominput():
     assert not f.isatty()
     pytest.raises(IOError, f.read)
     pytest.raises(IOError, f.readlines)
-    pytest.raises(IOError, iter, f)
+    iter_f = iter(f)
+    pytest.raises(IOError, next, iter_f)
     pytest.raises(UnsupportedOperation, f.fileno)
     f.close()  # just for completeness
 
@@ -764,7 +765,8 @@ def test_dontreadfrominput_buffer_python3():
     assert not fb.isatty()
     pytest.raises(IOError, fb.read)
     pytest.raises(IOError, fb.readlines)
-    pytest.raises(IOError, iter, fb)
+    iter_f = iter(f)
+    pytest.raises(IOError, next, iter_f)
     pytest.raises(ValueError, fb.fileno)
     f.close()  # just for completeness
 

From 2f47624b19d53db7667c54dd6bcf2232e1dc24e3 Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Thu, 15 Mar 2018 21:26:40 -0400
Subject: [PATCH 47/51] Allow DontReadFromInput to produce iterator without
 error. Fixes #3314.

---
 _pytest/capture.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/_pytest/capture.py b/_pytest/capture.py
index 6e2139445..6545e6fa3 100644
--- a/_pytest/capture.py
+++ b/_pytest/capture.py
@@ -574,7 +574,10 @@ class DontReadFromInput(object):
         raise IOError("reading from stdin while output is captured")
     readline = read
     readlines = read
-    __iter__ = read
+    __next__ = read
+
+    def __iter__(self):
+        return self
 
     def fileno(self):
         raise UnsupportedOperation("redirected stdin is pseudofile, "

From 965a030564be02f5926c1a579ff59dabf5702e37 Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Thu, 15 Mar 2018 21:30:29 -0400
Subject: [PATCH 48/51] Add changelog. Ref #3314.

---
 changelog/3314.bugfix.rst | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 changelog/3314.bugfix.rst

diff --git a/changelog/3314.bugfix.rst b/changelog/3314.bugfix.rst
new file mode 100644
index 000000000..4b671ec21
--- /dev/null
+++ b/changelog/3314.bugfix.rst
@@ -0,0 +1,3 @@
+During test collection, when stdin is not allowed to be read, the
+``DontReadFromStdin`` object still allow itself to be iterable and
+resolved to an iterator without crashing.

From b66019202ec389d5430434ace3068a8eb405402a Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Thu, 15 Mar 2018 21:33:58 -0400
Subject: [PATCH 49/51] Fix test failure on Python 2. Ref #3314.

---
 _pytest/capture.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_pytest/capture.py b/_pytest/capture.py
index 6545e6fa3..9f4f41c41 100644
--- a/_pytest/capture.py
+++ b/_pytest/capture.py
@@ -560,7 +560,7 @@ class SysCaptureBinary(SysCapture):
         return res
 
 
-class DontReadFromInput(object):
+class DontReadFromInput(six.Iterator):
     """Temporary stub class.  Ideally when stdin is accessed, the
     capturing should be turned off, with possibly all data captured
     so far sent to the screen.  This should be configurable, though,

From 17468fc99c0bee8efaffb7dfb506f23e3b30145f Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Fri, 16 Mar 2018 00:04:28 -0300
Subject: [PATCH 50/51] Fix caplog docstring: indentation caused errors during
 docs build

---
 _pytest/logging.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/_pytest/logging.py b/_pytest/logging.py
index c920659a5..b265ca34d 100644
--- a/_pytest/logging.py
+++ b/_pytest/logging.py
@@ -292,8 +292,7 @@ def caplog(request):
     * caplog.text()          -> string containing formatted log output
     * caplog.records()       -> list of logging.LogRecord instances
     * caplog.record_tuples() -> list of (logger_name, level, message) tuples
-    * caplog.clear()         -> clear captured records and formatted log output
-                                string
+    * caplog.clear()         -> clear captured records and formatted log output string
     """
     result = LogCaptureFixture(request.node)
     yield result

From 278d8ac74e6e86568f52ffdf92039de9213088c3 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Fri, 16 Mar 2018 00:04:28 -0300
Subject: [PATCH 51/51] Fix caplog docstring: indentation caused errors during
 docs build

---
 _pytest/logging.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/_pytest/logging.py b/_pytest/logging.py
index c920659a5..b265ca34d 100644
--- a/_pytest/logging.py
+++ b/_pytest/logging.py
@@ -292,8 +292,7 @@ def caplog(request):
     * caplog.text()          -> string containing formatted log output
     * caplog.records()       -> list of logging.LogRecord instances
     * caplog.record_tuples() -> list of (logger_name, level, message) tuples
-    * caplog.clear()         -> clear captured records and formatted log output
-                                string
+    * caplog.clear()         -> clear captured records and formatted log output string
     """
     result = LogCaptureFixture(request.node)
     yield result