Move most of 'builtin' to 'reference'

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
+For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures, type::
-typing on the Python interactive prompt something like::
+
+    $ 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

doc/en/contents.rst

@@ -14,7 +14,6 @@ Full pytest documentation
    usage
    existingtestsuite
    assert
-   builtin
    fixture
    monkeypatch
    tmpdir

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

doc/en/reference.rst

@@ -9,6 +9,26 @@ This page contains the full reference to pytest's API.
     :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`:
 
 Hooks
@@ -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: