docs: clarify automatic package detection

Author: nothing-991

docs/pyproject.md

@@ -574,74 +574,22 @@ based on the `python` requirement, use `project.classifiers` instead of this set
 
 A list of packages and modules to include in the final distribution.
 
-If your project structure differs from the standard one supported by `poetry`,
-you can specify the packages you want to include in the final distribution.
+Poetry can automatically detect your package without requiring `[tool.poetry.packages]` in common cases.
 
-```toml
-[tool.poetry]
-# ...
-packages = [
-    { include = "my_package" },
-    { include = "extra_package/**/*.py" },
-]
-```
-
-If your package is stored inside a "lib" directory, you must specify it:
-
-```toml
-[tool.poetry]
-# ...
-packages = [
-    { include = "my_package", from = "lib" },
-]
-```
-
-The `to` parameter is designed to specify the relative destination path
-where the package will be located upon installation. This allows for
-greater control over the organization of packages within your project's structure.
-
-```toml
-[tool.poetry]
-# ...
-packages = [
-    { include = "my_package", from = "lib", to = "target_package" },
-]
-```
+### Automatic package detection
 
-If you want to restrict a package to a specific build format, you can specify
-it by using `format`:
+Poetry can automatically detect packages if there exists either a **module** or a **package**
+whose name matches the project name (canonicalized: lowercase, with `-` replaced by `_`).
 
-```toml
-[tool.poetry]
-# ...
-packages = [
-    { include = "my_package" },
-    { include = "my_other_package", format = "sdist" },
-]
-```
+The detected module or package must be located in one of the following places:
 
-From now on, only the `sdist` build archive will include the `my_other_package` package.
-
-{{% note %}}
-Using `packages` disables the package auto-detection feature meaning you have to
-**explicitly** specify the "default" package.
+- **Flat layout:** at the same level as `pyproject.toml`
+- **Src layout:** inside a `src/` directory
 
-For instance, if you have a package named `my_package` and you want to also include
-another package named `extra_package`, you will need to specify `my_package` explicitly:
+These two layouts are considered the standard layouts.
 
-```toml
-packages = [
-    { include = "my_package" },
-    { include = "extra_package" },
-]
-```
-{{% /note %}}
-
-{{% note %}}
-Poetry is clever enough to detect Python subpackages.
-
-Thus, you only have to specify the directory where your root package resides.
-{{% /note %}}
+If packages are not automatically detected, you must explicitly define them using
+[`tool.poetry.packages`](#packages).
 
 ### exclude and include