docs: configuration for the src layout (#989)

* docs: configuration for the src layout

Expand the documentation to explain how to configure
the pythonpath for projects using the src layout.

Fix #738

* Fix incorrect formatting

Co-authored-by: Hasan Ramezani <[email protected]>

* Prefer the pytest 7 way

Co-authored-by: Hasan Ramezani <[email protected]>
Co-authored-by: Ran Benita <[email protected]>

Author: 3 people

docs/managing_python_path.rst

@@ -75,9 +75,39 @@ add this directly to your project's requirements.txt file like this::
     pytest-django
 
 
-Using pytest-pythonpath
-~~~~~~~~~~~~~~~~~~~~~~~
+Using pytest's ``pythonpath`` option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can explicitly add paths to the Python search path using pytest's
+:pytest-confval:`pythonpath` option.
+This option is available since pytest 7; for older versions you can use the
+`pytest-pythonpath <https://pypi.python.org/pypi/pytest-pythonpath>`_ plugin.
+
+Example: project with src layout
+````````````````````````````````
+
+For a Django package using the ``src`` layout, with test settings located in a 
+``tests`` package at the top level::
+
+    myproj
+    ├── pytest.ini
+    ├── src
+    │   └── myproj
+    │       ├── __init__.py
+    │       └── main.py
+    └── tests
+        ├── testapp
+        |   ├── __init__.py
+        |   └── apps.py
+        ├── __init__.py
+        ├── settings.py
+        └── test_main.py
+
+You'll need to specify both the top level directory and ``src`` for things to work::
 
-You can also use the `pytest-pythonpath
-<https://pypi.python.org/pypi/pytest-pythonpath>`_ plugin to explicitly add paths to
-the Python path.
+    [pytest]
+    DJANGO_SETTINGS_MODULE = tests.settings
+    pythonpath = . src
+
+If you don't specify ``.``, the settings module won't be found and
+you'll get an import error: ``ImportError: No module named 'tests'``.