📝 docs(readme): document TOML config file discovery

Author: gaborbernat

README.md

@@ -1,12 +1,12 @@
 # pytest-env
 
 [![PyPI](https://img.shields.io/pypi/v/pytest-env?style=flat-square)](https://pypi.org/project/pytest-env/)
-[![Supported Python
-versions](https://img.shields.io/pypi/pyversions/pytest-env.svg)](https://pypi.org/project/pytest-env/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pytest-env.svg)](https://pypi.org/project/pytest-env/)
 [![check](https://github.com/pytest-dev/pytest-env/actions/workflows/check.yaml/badge.svg)](https://github.com/pytest-dev/pytest-env/actions/workflows/check.yaml)
 [![Downloads](https://static.pepy.tech/badge/pytest-env/month)](https://pepy.tech/project/pytest-env)
 
-This is a `pytest` plugin that enables you to set environment variables in `pytest.ini`, `pyproject.toml`, `pytest.toml` or `.pytest.toml` files.
+This is a `pytest` plugin that enables you to set environment variables in `pytest.ini`, `pyproject.toml`, `pytest.toml`
+or `.pytest.toml` files.
 
 ## Installation
 
@@ -20,19 +20,19 @@ pip install pytest-env
 
 ### Native form in `pyproject.toml`, `pytest.toml` and `.pytest.toml`
 
-> [!NOTE]
-> `pytest.toml` and `.pytest.toml` is only supported on Pytest 9.0+.
+> [!NOTE] `pytest.toml` and `.pytest.toml` is only supported on Pytest 9.0+.
 
-Native form takes precedence over the `pytest.ini` form. `pytest.toml` takes precedence over `.pytest.toml`, and that takes precedence over `pyproject.toml`.
+Native form takes precedence over the `pytest.ini` form. `pytest.toml` takes precedence over `.pytest.toml`, and that
+takes precedence over `pyproject.toml`.
 
 In `pyproject.toml`:
 
 ```toml
 [tool.pytest_env]
 HOME = "~/tmp"
 RUN_ENV = 1
-TRANSFORMED = {value = "{USER}/alpha", transform = true}
-SKIP_IF_SET = {value = "on", skip_if_set = true}
+TRANSFORMED = { value = "{USER}/alpha", transform = true }
+SKIP_IF_SET = { value = "on", skip_if_set = true }
 ```
 
 In `pytest.toml` (or `.pytest.toml`):
@@ -41,17 +41,41 @@ In `pytest.toml` (or `.pytest.toml`):
 [pytest_env]
 HOME = "~/tmp"
 RUN_ENV = 1
-TRANSFORMED = {value = "{USER}/alpha", transform = true}
-SKIP_IF_SET = {value = "on", skip_if_set = true}
+TRANSFORMED = { value = "{USER}/alpha", transform = true }
+SKIP_IF_SET = { value = "on", skip_if_set = true }
 ```
 
-The `tool.pytest_env` (`pytest_env` in `pytest.toml` and `.pytest.toml`) tables keys are the environment variables keys to set. The right hand side of the assignment:
+The `tool.pytest_env` (`pytest_env` in `pytest.toml` and `.pytest.toml`) tables keys are the environment variables keys
+to set. The right hand side of the assignment:
 
 - if an inline table you can set options via the `transform` or `skip_if_set` keys, while the `value` key holds the
   value to set (or transform before setting). For transformation the variables you can use is other environment
   variable,
 - otherwise the value to set for the environment variable to set (casted to a string).
 
+### Configuration file discovery
+
+When using the native TOML form, `pytest-env` walks the directory tree starting from the directory containing the
+configuration file pytest resolved (`inipath`). For each directory it checks, in order: `pytest.toml`, `.pytest.toml`,
+and `pyproject.toml`. It stops at the first file that contains a `[pytest_env]` (or `[tool.pytest_env]` for
+`pyproject.toml`) section.
+
+This means a subdirectory with its own `pytest.toml` containing `[pytest_env]` takes precedence over a parent
+`pyproject.toml` with `[tool.pytest_env]`, as long as pytest resolves its config to that subdirectory:
+
+```
+project/
+├── pyproject.toml          # [tool.pytest_env] DB_HOST = "prod-db"
+└── tests_integration/
+    ├── pytest.toml          # [pytest_env] DB_HOST = "test-db"
+    └── test_api.py
+```
+
+Running `pytest tests_integration/` uses `DB_HOST = "test-db"` from the subdirectory config.
+
+If no TOML file with a `pytest_env` section is found, the plugin falls back to the INI-style `env` key from pytest
+configuration.
+
 ### Via pytest configurations
 
 In your pytest.ini file add a key value pair with `env` as the key and the environment variables as a line separated
@@ -69,8 +93,8 @@ Or with `pyproject.toml`:
 ```toml
 [tool.pytest.ini_options]
 env = [
-    "HOME=~/tmp",
-    "RUN_ENV=test",
+  "HOME=~/tmp",
+  "RUN_ENV=test",
 ]
 ```