doc: document consider_namespace_packages option

Author: nicoddemus

Diff for: changelog/11475.feature.rst

@@ -1,3 +1,3 @@
-pytest now correctly identifies modules that are part of `namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`__, for example when importing user-level modules for doctesting.
+Added the new :confval:`consider_namespace_packages` configuration option, defaulting to ``False``.
 
-Previously pytest was not aware of namespace packages, so running a doctest from a subpackage that is part of a namespace package would import just the subpackage (for example ``app.models``) instead of its full path (for example ``com.company.app.models``).
+If set to ``True``, pytest will attempt to identify modules that are part of `namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`__ when importing modules.

Diff for: changelog/11475.improvement.rst

@@ -1 +1,3 @@
 :ref:`--import-mode=importlib <import-mode-importlib>` now tries to import modules using the standard import mechanism (but still without changing :py:data:`sys.path`), falling back to importing modules directly only if that fails.
+
+This means that installed packages will be imported under their canonical name if possible first, for example ``app.core.models``, instead of having the module name always be derived from their path (for example ``.env310.lib.site_packages.app.core.models``).

Diff for: doc/en/explanation/pythonpath.rst

@@ -10,8 +10,7 @@ Import modes
 
 pytest as a testing framework needs to import test modules and ``conftest.py`` files for execution.
 
-Importing files in Python (at least until recently) is a non-trivial processes, often requiring
-changing :data:`sys.path`. Some aspects of the
+Importing files in Python is a non-trivial processes, so aspects of the
 import process can be controlled through the ``--import-mode`` command-line flag, which can assume
 these values:
 
@@ -100,10 +99,17 @@ these values:
     Initially we intended to make ``importlib`` the default in future releases, however it is clear now that
     it has its own set of drawbacks so the default will remain ``prepend`` for the foreseeable future.
 
+.. note::
+
+    By default, pytest will not attempt to resolve namespace packages automatically, but that can
+    be changed via the :confval:`consider_namespace_packages` configuration variable.
+
 .. seealso::
 
     The :confval:`pythonpath` configuration variable.
 
+    The :confval:`consider_namespace_packages` configuration variable.
+
     :ref:`test layout`.
 
 

Diff for: doc/en/reference/reference.rst

@@ -1274,6 +1274,19 @@ passed multiple times. The expected format is ``name=value``. For example::
    variables, that will be expanded. For more information about cache plugin
    please refer to :ref:`cache_provider`.
 
+.. confval:: consider_namespace_packages
+
+   Controls if pytest should attempt to identify `namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages>`__
+   when collecting Python modules. Default is ``False``.
+
+   Set to ``True`` if you are testing namespace packages installed into a virtual environment and it is important for
+   your packages to be imported using their full namespace package name.
+
+   Only `native namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages>`__
+   are supported, with no plans to support `legacy namespace packages <https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#legacy-namespace-packages>`__.
+
+   .. versionadded:: 8.1
+
 .. confval:: console_output_style
 
    Sets the console output style while running tests: