[Docs] Further clarification of package_dir behaviour

[cdfarrow]

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

[abravalheri]

Hi @cdfarrow thank you very much for the feedback, suggestions and the detailed explanations. They are very good.

I don't think we will be able to change the first link that belongs to the Python website, but we can indeed add a modified version of it to the setuptools website. (All the documentation for distutils is currently copied into the setuptools website in a "staging area", which means that they need to be revised, updated, changed to not mention distutils directly, and finally moved to a more obvious URL path -- that is likely to require a lot of work).

For the second link, we can indeed submit suggestions of changes to the packaging tutorial (the setuptools maintainers are not automatic maintainers of that tutorial). Alternatively we could also create our own tutorial in the setuptools website.

---

For anyone reading this issue: all contributions towards this goal would be extremely helpful and welcome. I can assist and answer to any doubts that might appear if someone would like to submit a PR.