Improve documentation around conftest-files and importing of fixtures

[The-Compiler]

Prompted by #13144, I looked at the fixtures documentation of pytest again, and I feel like we're not doing a very good job at explaining a quite basic concept: How to use conftest.py files on a basic level, and why fixtures shouldn't be imported. I'd even go as far as recommending a rule of thumb like "never import anything from a test file or from a conftest.py, unless it's for type annotations".

The section about scope could then perhaps have a note linking to that, to avoid confusion when something like in #13144 happens.

What we have so far:

How to use fixtures mentions conftest.py in passing, while actually talking about the scope argument (which seems extra confusing, even more so with the title of "scope: sharing fixtures", while scope is about the caching/lifetime and not the visibility!):

The next example puts the fixture function into a separate conftest.py file so that tests from multiple test modules in the directory can access the fixture function: [...]

In the same document, under Using fixtures from other projects, there is a note (emphasis mine):

Sometimes users will import fixtures from other projects for use, however this is not recommended: importing fixtures into a module will register them in pytest as defined in that module.

This has minor consequences, such as appearing multiple times in pytest --help, but it is not recommended because this behavior might change/stop working in future versions.

While the note is aimed at importing things from other non-test code, as seen in #13144, doing something very similar in the current's project test code can introduce confusion on why a fixture with scope="session" that's imported somewhere else is run twice.

Finally, only in the fixtures reference we have a section about conftest.py, which already goes into quite some technical detail with how nesting of multiple conftest.py works.

[andyDoucette]

Thank you for opening this, @The-Compiler! Right now it seems to me like we're trying to paint over a flaw in the design, but maybe once I read the new docs I'll understand why you guys did it the way you did.

Just for fun, can you also give equal thought to the "just change the behavior to be what python developers expect based on what they know about how python works" and weigh the pros and cons of both approaches? Sometimes changing the code to make it do the intuitive thing can be better than documenting the heck out of the non-intuitive thing. I can't say for sure if it's better, though, since I don't know the details of why it was designed the way it was - only someone with more experience in the pytest internals would know the challenges that needed to be overcome. I just know it's really counter-intuitive from a user standpoint. Thank you.