Improve docs

Author: nicoddemus

changelog/12749.feature.rst

@@ -1,5 +1,21 @@
-New :confval:`collect_imported_tests`: when enabled (the default) pytest will collect classes/functions in test modules even if they are imported from another file.
+pytest traditionally collects classes/functions in the test module namespace even if they are imported from another file.
 
-Setting this to False will make pytest collect classes/functions from test files only if they are defined in that file (as opposed to imported there).
+For example:
+
+.. code-block:: python
+
+    # contents of src/domain.py
+    class Testament: ...
+
+
+    # contents of tests/test_testament.py
+    from domain import Testament
+
+
+    def test_testament(): ...
+
+In this scenario with the default options, pytest will collect the class `Testament` from `tests/test_testament.py` because it starts with `Test`, even though in this case it is a production class being imported in the test module namespace.
+
+This behavior can now be prevented by setting the new :confval:`collect_imported_tests` configuration option to ``false``, which will make pytest collect classes/functions from test files **only** if they are defined in that file.
 
 -- by :user:`FreerGit`

doc/en/reference/reference.rst

@@ -1306,7 +1306,7 @@ passed multiple times. The expected format is ``name=value``. For example::
    .. versionadded:: 8.4
 
    Setting this to ``false`` will make pytest collect classes/functions from test
-   files only if they are defined in that file (as opposed to imported there).
+   files **only** if they are defined in that file (as opposed to imported there).
 
    .. code-block:: ini
 
@@ -1315,6 +1315,26 @@ passed multiple times. The expected format is ``name=value``. For example::
 
    Default: ``true``
 
+   pytest traditionally collects classes/functions in the test module namespace even if they are imported from another file.
+
+   For example:
+
+   .. code-block:: python
+
+       # contents of src/domain.py
+       class Testament: ...
+
+
+       # contents of tests/test_testament.py
+       from domain import Testament
+
+
+       def test_testament(): ...
+
+   In this scenario, with the default options, pytest will collect the class `Testament` from `tests/test_testament.py` because it starts with `Test`, even though in this case it is a production class being imported in the test module namespace.
+
+   Set ``collected_imported_tests`` to ``false`` in the configuration file prevents that.
+
 .. confval:: consider_namespace_packages
 
    Controls if pytest should attempt to identify `namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`__