Improve namespace packaging guide

Author: chrysle

source/guides/packaging-namespace-packages.rst

@@ -57,24 +57,15 @@ import object short).
 Creating a namespace package
 ============================
 
-There are currently three different approaches to creating namespace packages:
+There are currently two different approaches to creating namespace packages,
+from which the latter is discouraged:
 
 #. Use `native namespace packages`_. This type of namespace package is defined
    in :pep:`420` and is available in Python 3.3 and later. This is recommended if
    packages in your namespace only ever need to support Python 3 and
    installation via ``pip``.
-#. Use `pkgutil-style namespace packages`_. This is recommended for new
-   packages that need to support Python 2 and 3 and installation via both
-   ``pip`` and ``python setup.py install``.
-#. Use `pkg_resources-style namespace packages`_. This method is recommended if
-   you need compatibility with packages already using this method or if your
-   package needs to be zip-safe.
-
-.. warning:: While native namespace packages and pkgutil-style namespace
-    packages are largely compatible, pkg_resources-style namespace packages
-    are not compatible with the other methods. It's inadvisable to use
-    different methods in different distributions that provide packages to the
-    same namespace.
+#. Use `legacy namespace packages`_. This comprises `pkgutil-style namespace packages`_
+   and `pkg_resources-style namespace packages`_.
 
 Native namespace packages
 -------------------------
@@ -86,13 +77,14 @@ structure:
 
 .. code-block:: text
 
-    setup.py
-    mynamespace/
+    mynamespace-subpackage-a/
+        setup.py # AND/OR pyproject.toml, setup.cfg
+        mynamespace/ # namespace package
         # No __init__.py here.
-        subpackage_a/
-            # Sub-packages have __init__.py.
-            __init__.py
-            module.py
+            subpackage_a/
+                # Sub-packages have an __init__.py.
+                __init__.py
+                module.py
 
 It is extremely important that every distribution that uses the namespace
 package omits the :file:`__init__.py` or uses a pkgutil-style
@@ -112,8 +104,31 @@ list all packages in your :file:`setup.py`. For example:
         name='mynamespace-subpackage-a',
         ...
         packages=find_namespace_packages(include=['mynamespace.*'])
+        # or list a single package explicitly:
+        # packages=['mynamespace.subpackage_a'],
     )
 
+The same can be accomplished by replacing the :file:`setup.py` in the
+namespace packages' parent directory with a :file:`pyproject.toml`,
+with the following contents:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools", "setuptools-scm"]
+    build-backend = "setuptools.build_meta"
+
+    [tool.setuptools.packages.find]
+    where = ["."]
+    include = ["mynamespace.*"]
+
+    [project]
+    name = "mynamespace-subpackage-a"
+    ...
+
+:ref:`setuptools` will search the directory structure for implicit namespace
+packages by default.
+
 A complete working example of two native namespace packages can be found in
 the `native namespace package example project`_.
 
@@ -125,8 +140,25 @@ the `native namespace package example project`_.
     only support Python 3 and pkgutil-style namespace packages in the
     distributions that need to support Python 2 and 3.
 
+
+Legacy namespace packages
+-------------------------
+
+These to methods, that were used to create namespace packages prior to :pep:`420`,
+are now considered to be obsolete and should not be used unless you need compatibility
+with packages already using this method. Also, :doc:`pkg_resources <setuptools:pkg_resources>`
+has been deprecated.
+
+To migrate an existing package, all packages sharing the namespace must be migrated simultaneously.
+
+.. warning:: While native namespace packages and pkgutil-style namespace
+    packages are largely compatible, pkg_resources-style namespace packages
+    are not compatible with the other methods. It's inadvisable to use
+    different methods in different distributions that provide packages to the
+    same namespace.
+
 pkgutil-style namespace packages
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Python 2.3 introduced the :doc:`pkgutil <python:library/pkgutil>` module and the
 :py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace
@@ -138,22 +170,22 @@ To create a pkgutil-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py
+    setup.py # AND/OR pyproject.toml, setup.cfg
     mynamespace/
         __init__.py  # Namespace package __init__.py
         subpackage_a/
             __init__.py  # Sub-package __init__.py
             module.py
 
 The :file:`__init__.py` file for the namespace package needs to contain
-**only** the following:
+the following:
 
 .. code-block:: python
 
     __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
-**Every** distribution that uses the namespace package must include an
-identical :file:`__init__.py`. If any distribution does not, it will cause the
+**Every** distribution that uses the namespace package must include such
+an :file:`__init__.py`. If any distribution does not, it will cause the
 namespace logic to fail and the other sub-packages will not be importable.  Any
 additional code in :file:`__init__.py` will be inaccessible.
 
@@ -167,7 +199,7 @@ in the `pkgutil namespace example project`_.
 
 
 pkg_resources-style namespace packages
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :doc:`Setuptools <setuptools:index>` provides the `pkg_resources.declare_namespace`_ function and
 the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together
@@ -183,7 +215,7 @@ To create a pkg_resources-style namespace package, you need to provide an
 
 .. code-block:: text
 
-    setup.py
+    setup.py # AND/OR pyproject.toml, setup.cfg
     mynamespace/
         __init__.py  # Namespace package __init__.py
         subpackage_a/