[docs] Reword section about asyncio event loops in "concepts".

The section now explains the concept of "scoped loops".

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

Author: seifertm

docs/source/concepts.rst

@@ -4,19 +4,42 @@ Concepts
 
 asyncio event loops
 ===================
-pytest-asyncio runs each test item in its own asyncio event loop. The loop can be accessed via ``asyncio.get_running_loop()``.
-
-.. code-block:: python
-
-    async def test_runs_in_a_loop():
-        assert asyncio.get_running_loop()
-
-Synchronous test functions can get access to an asyncio event loop via the `event_loop` fixture.
-
-.. code-block:: python
-
-    def test_can_access_current_loop(event_loop):
-        assert event_loop
+In order to understand how pytest-asyncio works, it helps to understand how pytest collectors work.
+If you already know about pytest collectors, please :ref:`skip ahead <pytest-asyncio-event-loops>`.
+Otherwise, continue reading.
+Let's assume we have a test suite with a file named *test_all_the_things.py* holding a single test, async or not:
+
+.. include:: concepts_function_scope_example.py
+    :code: python
+
+The file *test_all_the_things.py* is a Python module with a Python test function.
+When we run pytest, the test runner descends into Python packages, modules, and classes, in order to find all tests, regardless whether the tests will run or not.
+This process is referred to as *test collection* by pytest.
+In our particular example, pytest will find our test module and the test function.
+We can visualize the collection result by running ``pytest --collect-only``::
+
+    <Module test_all_the_things.py>
+      <Function test_runs_in_a_loop>
+
+The example illustrates that the code of our test suite is hierarchical.
+Pytest uses so called *collectors* for each level of the hierarchy.
+Our contrived example test suite uses the *Module* and *Function* collectors, but real world test code may contain additional hierarchy levels via the *Package* or *Class* collectors.
+There's also a special *Session* collector at the root of the hierarchy.
+You may notice that the individual levels resemble the possible `scopes of a pytest fixture. <https://docs.pytest.org/en/7.4.x/how-to/fixtures.html#scope-sharing-fixtures-across-classes-modules-packages-or-session>`__
+
+.. _pytest-asyncio-event-loops:
+Pytest-asyncio provides one asyncio event loop for each pytest collector.
+By default, each test runs in the event loop provided by the *Function* collector, i.e. tests use the loop with the narrowest scope.
+This gives the highest level of isolation between tests.
+If two or more tests share a common ancestor collector, the tests can be configured to run in their ancestor's loop by passing the appropriate *scope* keyword argument to the *asyncio* mark.
+For example, the following two tests use the asyncio event loop provided by the *Module* collector:
+
+.. include:: concepts_module_scope_example.py
+    :code: python
+
+It's highly recommended for neighboring tests to use the same event loop scope.
+For example, all tests in a class or module should use the same scope.
+Assigning neighboring tests to different event loop scopes is discouraged as it can make test code hard to follow.
 
 Test discovery modes
 ====================

docs/source/concepts_function_scope_example.py

@@ -0,0 +1,8 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_runs_in_a_loop():
+    assert asyncio.get_running_loop()

docs/source/concepts_module_scope_example.py

@@ -0,0 +1,17 @@
+import asyncio
+
+import pytest
+
+loop: asyncio.AbstractEventLoop
+
+
+@pytest.mark.asyncio(scope="module")
+async def test_remember_loop():
+    global loop
+    loop = asyncio.get_running_loop()
+
+
+@pytest.mark.asyncio(scope="module")
+async def test_runs_in_a_loop():
+    global loop
+    assert asyncio.get_running_loop() is loop