[Docs] namespace package docs are ambiguous and possibly incorrect

Summary

PEP 420 prescribes the structure for implicit namespace packages, which are an often wanted feature from library developers coming from a "monorepo" mindset.

Unfortunately, the setuptools namespace docs and possibly also the actual build backend falls quite short in supporting it.

...as if there is only one timmins on your system. The two packages can then be distributed separately and installed individually without affecting the other one.

I simply disagree with this statement in documentation. If it's not wrong, then it is certainly unclear how to actually achieve this.

There is no explicitly shown directory tree, pyproject.toml meta-data table, or setup.py augmentation that directly or even indirectly shows how use setuptools to organize a collection of distinct python packages---each meant to be distributed separately---into a namespace package.

Indeed, the very next statement of the quote above in the docs explicitly switches context:

Now, suppose you decide to package the foo part for distribution...

This is problematic, because we already know how to package a single module / python package into distribution. It is irrelevant for packaging namespace packages. I want to know how to package a collection of distribution packages.

This can actually be verified by following the timmins and foo example given in the documentation. Both modules will be archived into the same wheel / source distribution.
It's actually unclear to me is setuptools support namespace packages, either explicit or implicit ones.

OS / Environment

N/A

Additional Information

If the docs were to be improved, there would be far less of a need for the many different extension packages that exist (such as setuptools-monorepo, poetry-multiproject, etc.)

Code of Conduct

• I agree to follow the PSF Code of Conduct

Start with the setuptools package discovery documentation and PEP 420, then reproduce the timmins and foo example to inspect the resulting wheel and source distribution. Clarify whether setuptools supports separate distributions within an implicit or explicit namespace, and document the directory tree and configuration needed for that arrangement.