[docs] Explain that scopes of event_loop fixtures should not overlap.

The example for overriding event loop scopes now uses a module scope rather than a session scope. Due to the constraint that event_loop fixture scopes should not overlap, a session-scoped fixture is usually not that helpful.

Addresses #531

Signed-off-by: Michael Seifert <[email protected]>

Author: seifertm

docs/source/reference/fixtures.rst

@@ -25,13 +25,18 @@ fixture scope, for example:
 
 .. code-block:: python
 
-    @pytest.fixture(scope="session")
+    @pytest.fixture(scope="module")
     def event_loop():
         policy = asyncio.get_event_loop_policy()
         loop = policy.new_event_loop()
         yield loop
         loop.close()
 
+When defining multiple ``event_loop`` fixtures, you should ensure that their scopes don't overlap.
+Each of the fixtures replace the running event loop, potentially without proper clean up.
+This will emit a warning and likely lead to errors in your tests suite.
+You can manually check for overlapping ``event_loop`` fixtures by running pytest with the ``--setup-show`` option.
+
 If you need to change the type of the event loop, prefer setting a custom event loop policy over redefining the ``event_loop`` fixture.
 
 If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop``