Most likely namespace packages explained wrongly

[8day]

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.