Merge pull request #3193 from pytest-dev/ref-docs

Reference docs

Author: nicoddemus

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 `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

_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,13 +292,18 @@ def close(self):
             cap.stop_capturing()
 
     def readouterr(self):
+        """Read and return the captured output so far, resetting the internal buffer.
+
+        :return: captured content as a namedtuple with  ``out`` and ``err`` string attributes
+        """
         try:
             return self._capture.readouterr()
         except AttributeError:
             return self._outerr
 
     @contextlib.contextmanager
     def disabled(self):
+        """Temporarily disables capture while inside the 'with' block."""
         self._capture.suspend_capturing()
         capmanager = self.request.config.pluginmanager.getplugin('capturemanager')
         capmanager.suspend_global_capture(item=None, in_=False)

_pytest/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;
     """

_pytest/doctest.py

@@ -379,6 +379,6 @@ def getvalue(self):
 @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()

_pytest/fixtures.py

@@ -858,7 +858,7 @@ def __call__(self, function):
 
 
 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
@@ -923,7 +923,15 @@ def yield_fixture(scope="function", params=None, autouse=False, ids=None, name=N
 
 @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
 
 

_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',

_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)
 
 

_pytest/python.py

@@ -717,7 +717,7 @@ def setall(self, funcargs, id, param):
 
 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.

_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

_pytest/recwarn.py

@@ -16,10 +16,7 @@
 
 @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 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 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

_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)

changelog/1713.doc.rst

@@ -0,0 +1 @@
+Added a `reference <https://docs.pytest.org/en/latest/reference.html>`_ page to the docs.

doc/en/_templates/globaltoc.html

@@ -2,15 +2,16 @@ <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
 
 <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>
-  <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 %}

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>