[Docs] Further clarification of package_dir behaviour

Summary

Further to the improvements to the keywords page, I think these sections could do with being edited for clarity:

2.1. Listing whole packages

If you use a different convention to lay out your source directory, that’s no problem: you just have to supply the package_dir option to tell the Distutils about your convention. For example, say you keep all Python source under lib, so that modules in the “root package” (i.e., not in any package at all) are in lib, modules in the foo package are in lib/foo, and so forth. Then you would put package_dir = {'': 'lib'} in your setup script.

The example syntax here is the same as for the "src layout", but the description seems to be saying that the Python source is directly under lib (as well as lib/foo) rather than in a sub-folder of lib. --> Make this clearer.

Further down it says:

A package: dir entry in the package_dir dictionary implicitly applies to all packages below package, so the foo.bar case is automatically handled here. In this example, having packages = ['foo', 'foo.bar'] tells the Distutils to look for lib/__init__.py and lib/bar/__init__.py. (Keep in mind that although package_dir applies recursively, you must explicitly list all packages in packages: the Distutils will not recursively scan your source tree looking for any directory with an __init__.py file.)

This sounds contradictory: it says, "the foo.bar case is automatically handled", but then foo.bar is included in the example packages= entry, and then it says, "you must explicitly list all packages in packages". So, is it automatic or not?; or are they talking about different things? In that case it could be made clearer.

Tutorial: Configuring metadata
Describing package_dir it says:

package_dir is a mapping of package names and directories. An empty package name represents the “root package” — the directory in the project that contains all Python source files for the package — so in this case the src directory is designated the root package.

--> update and clarify in line with the changes to keywords.rst

OS / Environment

No response

Additional Information

.

Code of Conduct

• I agree to follow the PSF Code of Conduct

Start with the linked “Listing whole packages” section, the keywords.rst changes referenced in the issue, and the linked packaging tutorial’s package_dir section. Clarify the distinction between package_dir’s recursive path mapping and the explicit packages list, then align the tutorial wording with keywords.rst and verify all referenced examples remain consistent.