Docs+Tests: clarify special discovery of pytest_generate_tests

[CoretexShadow]

Summary
This PR improves the documentation and tests around the special discovery rules of pytest_generate_tests. Unlike most hooks (which must live in conftest.py or plugins), pytest_generate_tests is also discovered when defined directly inside test modules or classes. This PR clarifies that behavior in the docs and adds a minimal self-test that shows the difference.

Motivation
New users often get confused about where hooks should be placed. By explicitly pointing out that pytest_generate_tests is the only exception to the “hooks go in conftest/plugins” rule, we reduce misunderstandings and make the docs easier to follow.

Changes

• Updated doc/en/how-to/writing_hook_functions.rst with a clear note on the exception for pytest_generate_tests.
• Updated doc/en/how-to/parametrize.rst with a short reminder in the relevant section.
• Added testing/test_pytest_generate_tests_discovery.py, which demonstrates that pytest_generate_tests inside a test module works, while pytest_terminal_summary does not.

Tests

• Confirms pytest_generate_tests in a test module parametrizes correctly.
• Confirms another hook (pytest_terminal_summary) inside a test module is ignored.

Docs
Only minimal “Note:” additions with cross-links, written for clarity and easy review.

Notes
No behavior changes — purely docs and tests. Pre-commit, mypy, and docs build all pass locally.

Related Issue
Closes #13577

[RonnyPfannschmidt]

Nice enhancement, thanks

[The-Compiler]

The doc improvements make a lot of sense, but not a fan of having an entire new test file just for a single test.

Also the test seems redundant to me: That pytest_generate_tests can be invoked on a class is already covered in testing/python/metafunc.py in test_generate_tests_in_class, and that other hooks don't work there is somewhat covered by test_runtest_in_module_ordering in testing/test_runner.py (see the xfail and the comment above).

Thus I'd propose to delete the new test file and only keep the doc adjustments.

[CoretexShadow]

Nice enhancement, thanks

Thanks 🙏

Just FYI: after separate feedback from The-Compiler I dropped the extra test and kept this as a docs-only PR.
If you’d like a different placement/wording for the note, I’m happy to tweak.

[CoretexShadow]

The doc improvements make a lot of sense, but not a fan of having an entire new test file just for a single test.

Also the test seems redundant to me: That pytest_generate_tests can be invoked on a class is already covered in testing/python/metafunc.py in test_generate_tests_in_class, and that other hooks don't work there is somewhat covered by test_runtest_in_module_ordering in testing/test_runner.py (see the xfail and the comment above).

Thus I'd propose to delete the new test file and only keep the doc adjustments.

Thanks for the detailed review — agreed.

I verified the existing coverage you pointed to:

• class case: testing/python/metafunc.py::test_generate_tests_in_class
• “other hooks don’t run from test modules”: testing/test_runner.py::test_runtest_in_module_ordering (saw the xfail + explanatory comment)

I’ve dropped the redundant test file:

• removed testing/test_pytest_generate_tests_discovery.py

and kept this PR docs-only to clarify the special discovery rules of pytest_generate_tests:

• doc/en/how-to/writing_hook_functions.rst (short note + cross-links)
• doc/en/how-to/parametrize.rst (concise reminder near the basic example)

Local checks re-run and passing (pre-commit / pytest / docs build).
Happy to tweak wording/placement if you prefer.

[The-Compiler]

Thanks!

[patchback]

Backport to 8.4.x: 💚 backport PR created

✅ Backport PR branch: patchback/backports/8.4.x/12bde8af6dda3e7104f840209c199d151258b462/pr-13685

Backported as #13686

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[glasser]

Thanks!