Small documentation improvements

Author: nicoddemus

CHANGELOG.rst

@@ -116,10 +116,11 @@
   Example '-o xfail_strict=True'. A complete ini-options can be viewed
   by py.test --help. Thanks `@blueyed`_ and `@fengxx`_ for the PR
 
-* New scope for fixtures: ``"invocation"``. This fixtures may be requested by fixtures from
-  any scope, when they assume the same scope as the fixture requesting it. An ``invocation``-scoped
-  fixture can be requested from different scopes in the same test session,
-  in which case each scope will have its own copy. This feature is considered experimental.
+* Experimentally introduce new ``"invocation"`` fixture scope. At invocation scope a
+  fixture function is cached in the same way as the fixture or test function that requests it.
+  You can now use the builtin ``monkeypatch`` fixture from ``session``-scoped fixtures
+  where previously you would get an error that you can not use a ``function``-scoped fixture from a
+  ``session``-scoped one.*
   Thanks `@nicoddemus`_ for the PR.
 
 *

_pytest/fixtures.py

@@ -1074,9 +1074,7 @@ def parsefactories(self, node_or_obj, nodeid=NOTSET, unittest=False):
                 assert not name.startswith(self._argprefix), name
 
             def new_fixture_def(name, scope):
-                """
-                Creates and registers a new FixtureDef with given name and scope.
-                """
+                """Create and registers a new FixtureDef with given name and scope."""
                 fixture_def = FixtureDef(self, nodeid, name, obj,
                                          scope, marker.params,
                                          unittest=unittest, ids=marker.ids)
@@ -1126,7 +1124,7 @@ def _matchfactories(self, fixturedefs, nodeid):
     def getfixturedefs_multiple_scopes(self, argname, nodeid):
         """
         Gets multiple scoped fixtures which are applicable to the given nodeid. Multiple scoped
-        fixtures are usually created by "invocation" scoped fixtures and have argnames in
+        fixtures are created by "invocation" scoped fixtures and have argnames in
         the form: "<argname>:<scope>" (for example "tmpdir:session").
 
         :return: dict of "argname" -> [FixtureDef].

doc/en/invocation-fixture.rst

@@ -37,6 +37,11 @@ value and can manage processes which will live for the duration of the scope.
 
     @pytest.fixture(scope='invocation')
     def process_manager():
+        """
+        Return a ProcessManager instance which can be used to start
+        long-lived processes and ensures they are terminated at the
+        appropriate scope.
+        """
         m = ProcessManager()
         yield m
         m.shutdown_all()