docs: Clarify deprecation of event_loop fixture.

Author: seifertm

docs/reference/fixtures/index.rst

@@ -4,6 +4,13 @@ Fixtures
 
 event_loop
 ==========
+*This fixture is deprecated.*
+
+*If you want to request an asyncio event loop with a scope other than function
+scope, use the "loop_scope" argument to* :ref:`reference/markers/asyncio` *when marking the tests.
+If you want to return different types of event loops, use the* :ref:`reference/fixtures/event_loop_policy`
+*fixture.*
+
 Creates a new asyncio event loop based on the current event loop policy. The new loop
 is available as the return value of this fixture for synchronous functions, or via `asyncio.get_running_loop <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.get_running_loop>`__ for asynchronous functions.
 The event loop is closed when the fixture scope ends.
@@ -20,6 +27,8 @@ If you need to change the type of the event loop, prefer setting a custom event
 If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop``
 fixture will be requested automatically by the test function.
 
+.. _reference/fixtures/event_loop_policy:
+
 event_loop_policy
 =================
 Returns the event loop policy used to create asyncio event loops.

docs/reference/markers/index.rst

@@ -2,6 +2,8 @@
 Markers
 =======
 
+.. _reference/markers/asyncio:
+
 ``pytest.mark.asyncio``
 =======================
 A coroutine or async generator with this marker is treated as a test function by pytest.