Split up docs

Author: tjkuson

docs/how-to-guides/custom_loop_factory.rst

@@ -21,26 +21,6 @@ pytest-asyncio can run asynchronous tests with custom event loop factories by im
            "custom": CustomEventLoop,
        }
 
-By default, each pytest-asyncio test is run once per configured factory. Tests managed by other async plugins are unaffected. Synchronous tests are not parametrized. The configured loop scope still determines how long each event loop instance is kept alive.
+See :doc:`run_test_with_specific_loop_factories` for running tests with only a subset of configured factories.
 
-Factories should be callables without required parameters and should return an ``asyncio.AbstractEventLoop`` instance. The effective hook result must be a non-empty mapping of non-empty string names to callables.
-
-To run a test with only a subset of configured factories, use the ``loop_factories`` argument of ``pytest.mark.asyncio``:
-
-.. code-block:: python
-
-   import pytest
-
-
-   @pytest.mark.asyncio(loop_factories=["custom"])
-   async def test_only_with_custom_event_loop():
-       pass
-
-
-If ``loop_factories`` contains unknown names, pytest-asyncio raises a ``pytest.UsageError`` during collection.
-
-When multiple ``pytest_asyncio_loop_factories`` implementations are present, pytest-asyncio uses the first non-``None`` result in pytest's hook dispatch order.
-
-.. note::
-
-   When the hook is defined, async tests are parametrized via ``pytest.metafunc.parametrize``, and mapping keys are used as test IDs. For example, a test ``test_example`` with an event loop factory key ``foo`` will appear as ``test_example[foo]`` in test output.
+See :doc:`../reference/hooks` and :doc:`../reference/markers/index` for the hook and marker reference.

docs/how-to-guides/index.rst

@@ -11,6 +11,7 @@ How-To Guides
   change_default_fixture_loop
   change_default_test_loop
   custom_loop_factory
+  run_test_with_specific_loop_factories
   run_class_tests_in_same_loop
   run_module_tests_in_same_loop
   run_package_tests_in_same_loop

docs/how-to-guides/run_test_with_specific_loop_factories.rst

@@ -0,0 +1,14 @@
+=========================================================
+How to run a test with specific event loop factories only
+=========================================================
+
+To run a test with only a subset of configured factories, use the ``loop_factories`` argument of ``pytest.mark.asyncio``:
+
+.. code-block:: python
+
+   import pytest
+
+
+   @pytest.mark.asyncio(loop_factories=["custom"])
+   async def test_only_with_custom_event_loop():
+       pass

docs/reference/hooks.rst

@@ -0,0 +1,16 @@
+=====
+Hooks
+=====
+
+``pytest_asyncio_loop_factories``
+=================================
+
+This hook returns a mapping from factory name strings to event loop factory callables for the current test item.
+
+By default, each pytest-asyncio test is run once per configured factory. Tests managed by other async plugins are unaffected. Synchronous tests are not parametrized. The configured loop scope still determines how long each event loop instance is kept alive.
+
+Factories should be callables without required parameters and should return an ``asyncio.AbstractEventLoop`` instance. The effective hook result must be a non-empty mapping of non-empty string names to callables.
+
+When multiple ``pytest_asyncio_loop_factories`` implementations are present, pytest-asyncio uses the first non-``None`` result in pytest's hook dispatch order.
+
+When the hook is defined, async tests are parametrized via ``pytest.metafunc.parametrize``, and mapping keys are used as test IDs. For example, a test ``test_example`` with an event loop factory key ``foo`` will appear as ``test_example[foo]`` in test output.

docs/reference/index.rst

@@ -8,6 +8,7 @@ Reference
   configuration
   fixtures/index
   functions
+  hooks
   markers/index
   decorators/index
   changelog

docs/reference/markers/index.rst

@@ -36,6 +36,8 @@ Subpackages do not share the loop with their parent package.
 
 Tests marked with *session* scope share the same event loop, even if the tests exist in different packages.
 
+The ``pytest.mark.asyncio`` marker also accepts a ``loop_factories`` keyword argument to select a subset of configured event loop factories for a test. If ``loop_factories`` contains unknown names, pytest-asyncio raises a ``pytest.UsageError`` during collection.
+
 .. |auto mode| replace:: *auto mode*
 .. _auto mode: ../../concepts.html#auto-mode
 .. |pytestmark| replace:: ``pytestmark``