Most likely namespace packages explained wrongly

E.g., compare examples at https://packaging.python.org/guides/packaging-namespace-packages/#packaging-namespace-packages and https://www.python.org/dev/peps/pep-0420/#examples. I.e., using examples from packaging.python.org, packages will be merged upon installation, whereas the very purpose of namespace packages is to avoid this.

This example:

mynamespace-subpackage-a/
    setup.py
    mynamespace/
        subpackage_a/
            __init__.py

mynamespace-subpackage-b/
    setup.py
    mynamespace/
        subpackage_b/
            __init__.py
        module_b.py

Must look like this:

mynamespace-subpackage-a/
    setup.py
    mynamespace_subpackage_a/
        mynamespace/
            subpackage_a/
                __init__.py

mynamespace-subpackage-b/
    setup.py
    mynamespace_subpackage_b/
        mynamespace/
            subpackage_b/
                __init__.py
            module_b.py

Also, for namespace to be found, its parent dir must be in sys.path, which is demonstrated at https://www.python.org/dev/peps/pep-0420/#examples. The effect of inclusion of mynamespace_subpackage_a dir in sys.path can be achieved by including file mynamespace_subpackage_a.pth with ./mynamespace_subpackage_a inside of it into mynamespace_subpackage_a. The same must be done for mynamespace_subpackage_b. Thus, final example should look like this:

mynamespace-subpackage-a/
    setup.py
    mynamespace_subpackage_a.pth # With ``./mynamespace_subpackage_a`` inside of it.
    mynamespace_subpackage_a/
        mynamespace/
            subpackage_a/
                __init__.py

mynamespace-subpackage-b/
    setup.py
    mynamespace_subpackage_b.pth # With ``./mynamespace_subpackage_b`` inside of it.
    mynamespace_subpackage_b/
        mynamespace/
            subpackage_b/
                __init__.py
            module_b.py

Obviously, setup.py must be updated as well.

BTW, this issue may be related to #689.

Edit:
It may be worth telling that too many paths in sys.path are likely to have negative impact on performance.

I'm not sure if I'm right about the actual implementation, but examples definitely look wrong.

Compare the namespace-package examples in the Packaging User Guide with the PEP 420 examples linked in the issue, and review related issue #689. Verify the claims about installation, sys.path, .pth files, and setup.py before updating the documentation examples and explaining the correct layout and behavior.