[docs] Extracted most Python code examples into separate files.

This allows for auto-formatting using the usual tools and enables running the code examples as tests to ensure they work.

Tests that perform network operations or require additional test dependencies have been excluded.

Signed-off-by: Michael Seifert <m.seifert@digitalernachschub.de>

docs/source/reference/decorators/fixture_strict_mode_example.py

@@ -0,0 +1,14 @@
+import asyncio
+
+import pytest_asyncio
+
+
+@pytest_asyncio.fixture
+async def async_gen_fixture():
+    await asyncio.sleep(0.1)
+    yield "a value"
+
+
+@pytest_asyncio.fixture(scope="module")
+async def async_fixture():
+    return await asyncio.sleep(0.1)

docs/source/reference/decorators.rst → docs/source/reference/decorators/index.rst

@@ -3,20 +3,8 @@ Decorators
 ==========
 Asynchronous fixtures are defined just like ordinary pytest fixtures, except they should be decorated with ``@pytest_asyncio.fixture``.
 
-.. code-block:: python3
-
-    import pytest_asyncio
-
-
-    @pytest_asyncio.fixture
-    async def async_gen_fixture():
-        await asyncio.sleep(0.1)
-        yield "a value"
-
-
-    @pytest_asyncio.fixture(scope="module")
-    async def async_fixture():
-        return await asyncio.sleep(0.1)
+.. include:: fixture_strict_mode_example.py
+    :code: python
 
 All scopes are supported, but if you use a non-function scope you will need
 to redefine the ``event_loop`` fixture to have the same or broader scope.

docs/source/reference/fixtures/event_loop_example.py

@@ -0,0 +1,5 @@
+import asyncio
+
+
+def test_event_loop_fixture(event_loop):
+    event_loop.run_until_complete(asyncio.sleep(0))

docs/source/reference/fixtures.rst → docs/source/reference/fixtures/index.rst

@@ -9,12 +9,8 @@ is available as the return value of this fixture or via `asyncio.get_running_loo
 The event loop is closed when the fixture scope ends. The fixture scope defaults
 to ``function`` scope.
 
-.. code-block:: python
-
-    def test_http_client(event_loop):
-        url = "http://httpbin.org/get"
-        resp = event_loop.run_until_complete(http_client(url))
-        assert b"HTTP/1.1 200 OK" in resp
+.. include:: event_loop_example.py
+    :code: python
 
 Note that, when using the ``event_loop`` fixture, you need to interact with the event loop using methods like ``event_loop.run_until_complete``. If you want to *await* code inside your test function, you need to write a coroutine and use it as a test function. The `asyncio <#pytest-mark-asyncio>`__ marker
 is used to mark coroutines that should be treated as test functions.

docs/source/reference/index.rst

@@ -6,9 +6,9 @@ Reference
   :hidden:
 
   configuration
-  fixtures
-  markers
-  decorators
+  fixtures/index
+  markers/index
+  decorators/index
   changelog
 
 This section of the documentation provides descriptions of the individual parts provided by pytest-asyncio.

docs/source/reference/markers/class_scoped_loop_auto_mode_example.py

@@ -0,0 +1,14 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio_event_loop
+class TestClassScopedLoop:
+    loop: asyncio.AbstractEventLoop
+
+    async def test_remember_loop(self):
+        TestClassScopedLoop.loop = asyncio.get_running_loop()
+
+    async def test_this_runs_in_same_loop(self):
+        assert asyncio.get_running_loop() is TestClassScopedLoop.loop

docs/source/reference/markers/class_scoped_loop_custom_policies_strict_mode_example.py

@@ -0,0 +1,15 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio_event_loop(
+    policy=[
+        asyncio.DefaultEventLoopPolicy(),
+        asyncio.DefaultEventLoopPolicy(),
+    ]
+)
+class TestWithDifferentLoopPolicies:
+    @pytest.mark.asyncio
+    async def test_parametrized_loop(self):
+        pass

docs/source/reference/markers/class_scoped_loop_custom_policy_strict_mode_example.py

@@ -0,0 +1,14 @@
+import asyncio
+
+import pytest
+
+
+class CustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+    pass
+
+
+@pytest.mark.asyncio_event_loop(policy=CustomEventLoopPolicy())
+class TestUsesCustomEventLoopPolicy:
+    @pytest.mark.asyncio
+    async def test_uses_custom_event_loop_policy(self):
+        assert isinstance(asyncio.get_event_loop_policy(), CustomEventLoopPolicy)

docs/source/reference/markers/class_scoped_loop_strict_mode_example.py

@@ -0,0 +1,16 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio_event_loop
+class TestClassScopedLoop:
+    loop: asyncio.AbstractEventLoop
+
+    @pytest.mark.asyncio
+    async def test_remember_loop(self):
+        TestClassScopedLoop.loop = asyncio.get_running_loop()
+
+    @pytest.mark.asyncio
+    async def test_this_runs_in_same_loop(self):
+        assert asyncio.get_running_loop() is TestClassScopedLoop.loop

docs/source/reference/markers/class_scoped_loop_with_fixture_strict_mode_example.py

@@ -0,0 +1,18 @@
+import asyncio
+
+import pytest
+
+import pytest_asyncio
+
+
+@pytest.mark.asyncio_event_loop
+class TestClassScopedLoop:
+    loop: asyncio.AbstractEventLoop
+
+    @pytest_asyncio.fixture
+    async def my_fixture(self):
+        TestClassScopedLoop.loop = asyncio.get_running_loop()
+
+    @pytest.mark.asyncio
+    async def test_runs_is_same_loop_as_fixture(self, my_fixture):
+        assert asyncio.get_running_loop() is TestClassScopedLoop.loop