Not sure about this one. This would include all the test cases in the examples given in the docs, making them quite cluttered. I think I'd prefer having them separated. It also breaks with the pattern of having them in tests/examples. We should at least be consistent there.

oO I entirely missed this test folder and I'll adapt to using it.

this said this is contradictory with #3362 where we have some test in docs/examples/.../test_xxx.py

2 proposals to make it consistent:

1. what about we use literalinclude: file.py instead of codeblock then we have a test inside tests/examples/file.py ?
2. what if we add a tab in docs on some code examples to show the corresponding test, idk how esthetically it could appear for the reader so that it doesnt feel cluttered but I think this brings value and promotes a test-oriented first mindset.

this said this is contradictory with #3362 where we have some test in docs/examples/.../test_xxx.py

Ah, I think I was misunderstanding what you were proposing there. Sorry for the confusion.

1. what about we use literalinclude: file.py instead of codeblock then we have a test inside tests/examples/file.py ?

That's the general idea, and I think how it's done for all things that use literalinclude and have tests. The only exception afaik are the examples for litestar.testing, which themselves are tests, so we just run those directly with pytest.

2. what if we add a tab in docs on some code examples to show the corresponding test, idk how esthetically it could appear for the reader so that it doesnt feel cluttered but I think this brings value and promotes a test-oriented first mindset.

I like the idea!

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/4099