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 01/38] 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 02/38] 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 03/38] 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 04/38] 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 05/38] 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 06/38] 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 07/38] 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 08/38] 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 09/38] 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 10/38] 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 11/38] 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 12/38] 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 13/38] 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 14/38] 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 15/38] 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 16/38] 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 17/38] 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 18/38] 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 19/38] 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 20/38] 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 21/38] 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 22/38] 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 23/38] 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 24/38] 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 25/38] 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 26/38] 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 27/38] 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 28/38] 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 29/38] 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 30/38] 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 31/38] 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 32/38] 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 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 33/38] 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 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 34/38] 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 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 35/38] 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 36/38] 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 37/38] 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 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 38/38] 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