Add documentation for "invocation" scoped fixture

Author: nicoddemus

doc/en/fixture.rst

@@ -603,7 +603,7 @@ first execute with one instance and then finalizers are called
 before the next fixture instance is created.  Among other things,
 this eases testing of applications which create and use global state.
 
-The following example uses two parametrized funcargs, one of which is
+The following example uses two parametrized fixture, one of which is
 scoped on a per-module basis, and all the functions perform ``print`` calls
 to show the setup/teardown flow::
 
@@ -863,6 +863,14 @@ All test methods in this TestClass will use the transaction fixture while
 other test classes or functions in the module will not use it unless
 they also add a ``transact`` reference.
 
+invocation-scoped fixtures
+--------------------------
+
+pytest 3.0 introduced a new advanced scope for fixtures: ``"invocation"``. Fixtures marked with
+this scope can be requested from any other scope, providing a version of the fixture for that scope.
+
+See more in :ref:`invocation_scoped_fixture`.
+
 Shifting (visibility of) fixture functions
 ----------------------------------------------------
 

doc/en/invocation-fixture.rst

@@ -0,0 +1,61 @@
+.. _invocation_scoped_fixture:
+
+Invocation-scoped fixtures
+==========================
+
+.. versionadded:: 3.0
+
+.. note::
+    This feature is experimental, so if decided that it brings too much problems
+    or considered too complicated it might be removed in pytest ``3.1``.
+
+    ``tmpdir`` and ``monkeypatch`` might become ``invocation`` scoped
+    fixtures in the future if decided to keep invocation-scoped fixtures.
+
+Fixtures can be defined with ``invocation`` scope, meaning that the fixture
+can be requested by fixtures from any scope, but when they do 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.
+
+Example
+-------
+
+Consider a fixture which manages external process execution:
+this fixture provides auxiliary methods for tests and fixtures to start external
+processes while making sure the
+processes terminate at the appropriate time. Because it makes sense
+to start a webserver for the entire session and also to execute a numerical
+simulation for a single test function, the ``process_manager``
+fixture can be declared as ``invocation``, so each scope gets its own
+value and can manage processes which will live for the duration of the scope.
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.fixture(scope='invocation')
+    def process_manager():
+        m = ProcessManager()
+        yield m
+        m.shutdown_all()
+
+
+    @pytest.fixture(scope='session')
+    def server(process_manager):
+        process_manager.start(sys.executable, 'server.py')
+
+
+    @pytest.fixture(scope='function')
+    def start_simulation(process_manager):
+        import functools
+        return functools.partial(process_manager.start,
+                                 sys.executable, 'simulator.py')
+
+
+In the above code, simulators started using ``start_simulation`` will be
+terminated when the test function exits, while the server will be kept
+active for the entire simulation run, being terminated when the test session
+finishes.
+