Document selecting loop factories per test

[tjkuson]

Document in more detail how to select loop factories per test (specifically, how the hook interacts with the loop_factories parameter).

The gist of what this is trying to do is document how loop_factories works alongside pytest's ordinary hook semantics.

Relates to #1101 (comment)

CI is failing as I didn't update the changelog. My understanding is that this PR can skip the changelog as the documentation hasn't been released yet.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.50%. Comparing base (31772d2) to head (f1a4d0d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1432   +/-   ##
=======================================
  Coverage   94.50%   94.50%           
=======================================
  Files           2        2           
  Lines         510      510           
  Branches       62       62           
=======================================
  Hits          482      482           
  Misses         22       22           
  Partials        6        6           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[seifertm]

The pytest-asyncio test suite discovers tests in Python files under the docs directory. This allows executing the code examples in the documentation and make it less likely for them to be outdated or break. This is currently done via an include directive, such as in parametrize_with_asyncio.{rst.py}.

Would it be possible to use the same approach for these two code examples? I imagine it would just work when grouping both of them into a subfolder under how-to-guides/.

If it doesn't work straight away, we leave it as is.

[tjkuson]

Seems to work. 0a1803d

[seifertm]

The first part up to line 18 explains that all tests are parametrized with whatever entries are returned by the hook and that users can limit the parametrization via the loop_factories argument in the asyncio marker. The added code examples show an "inverted" control flow: there's no parametrization by default, unless the user explicitly lists the factory identifier in loop_factories.

I understand that we want to show both and each content makes sense, but it could be confusing that two approaches are mixed.

I'm not sure how to best solve this. We could either highlight that these are two very different approaches, e.g. "Variant 1, Variant 2" headlines or keep both variants in separate how-tos. I'm leaning towards the latter, but I'm failing to come up with distinguishable how-to titles.

[tjkuson]

Yeah, I see what you mean.

I revisited how Diátaxis works and I think there's a reasonable argument in favour of this being three separate how-to guides: how to declare the event loop factories; how to declare factories based on item-specific logic; and how to select a subset of available factories from a test. I am curious what you think: 0a1803d f1a4d0d