Allow switching doc examples between auto and strict mode

[seifertm]

Users of pytest-asyncio either use auto mode or strict mode. They cannot mix modes within the same project. Some code examples in the documentation are presented for each mode, but the user is only interested for the examples in one of the modes.

I propose to add sphinx-tabs to the doc dependencies and use group tabs to show only code examples for the selected pytest-asyncio mode.

Code examples that are only available for one mode should be provided for both, auto mode and strict mode as part of this issue.

[enioxt]

Hi! 👋

I'd like to help implement the mode switching for doc examples.

Understanding

Need to add configuration to toggle between auto and strict asyncio mode in documentation examples, making it easier to demonstrate both patterns.

Proposed Approach

1. Add Sphinx config option (e.g., asyncio_example_mode)
2. Update doc examples with conditional rendering
3. Create switch mechanism (tabs or toggle)
4. Ensure examples are tested in both modes

Questions

1. Prefer Sphinx tabs extension or custom JS toggle?
2. Should both modes be visible simultaneously or switchable?
3. Any specific examples that need priority?

Experience

Maintainer of EGOS v.2 with comprehensive async patterns and testing documentation. Familiar with Sphinx + pytest integration.

Timeline: 3-4 days

Let me know if this approach works!

[seifertm]

Thanks for the initiative @enioxt !

1. Prefer Sphinx tabs extension or custom JS toggle?

I prefer the existing Sphinx extension, because I expect it to be less effort maintaining a dependency on it as opposed to maintaining custom JavaScript.

2. Should both modes be visible simultaneously or switchable?

They should be switchable.

Let's assume a user already has a code base that uses pytest-asyncio. They go to the documentation with a specific problem. The intention of the switchable code examples is to allow users to "customize" the appearance of the documentation to their specific environment. If the users' project uses strict mode, I want them to be able to view and copy-paste code examples for strict mode.

Right now, the idea focuses around strict mode and auto mode, but it's entirely possible that code examples will be different for different versions of Python in the future.

3. Any specific examples that need priority?

Not really, no. The goal of this issue is to have a mechanism in the documentation setup that allows switching code examples. We can adjust the documentation gradually to use that.

Proposed Approach

1. Add Sphinx config option (e.g., `asyncio_example_mode`)

2. Update doc examples with conditional rendering

3. Create switch mechanism (tabs or toggle)

4. Ensure examples are tested in both modes

What purpose does the config option serve?

[enioxt]

Thanks for the clarification @seifertm!

Perfect, I'll go with the Sphinx tabs extension approach then. That makes total sense, less maintenance overhead.

Regarding the config option I mentioned, i realize now that's not needed. The sphinx-tabs extension handles the switching mechanism natively through the UI, so there's no need for a separate config option. Users will simply click tabs to switch between auto mode and strict mode examples as they need.

My updated plan:

1. Add sphinx-tabs to docs/requirements.txt
2. Configure sphinx_tabs extension in docs/conf.py
3. Audit existing examples and identify which need both modes
4. Convert examples to use group tabs (::: {tab} Auto Mode / ::: {tab} Strict Mode)
5. Fill in missing mode examples where needed
6. Test documentation builds correctly

I'll start working on this and open a PR once the basic structure is in place. Feel free to point out if you'd like me to focus on any specific documentation sections first, even though you mentioned no specific priority.

Thanks again for the feedback!

[seifertm]

Sounds good, thank you!

Please do file the PR even if you don't manage to go through all examples in the docs. A partial documentation update with mode switching is better than none at all.

Let me know if you run into any issues.

My updated plan:

1. Add sphinx-tabs to docs/requirements.txt

Small nit: it should go to the optional-dependencies.docs section in pyproject.toml and to constraints.txt.