Clarify include/exclude in docs about package discovery (#3420)

1 files changed, 11 insertions, 16 deletions

diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
index 93419a24..2efc62b9 100644
--- a/docs/userguide/package_discovery.rst
+++ b/docs/userguide/package_discovery.rst
@@ -156,8 +156,7 @@ all modules and packages meant for distribution are placed inside this
 directory::
 
     project_root_directory
-    ├── pyproject.toml
-    ├── setup.cfg  # or setup.py
+    ├── pyproject.toml  # AND/OR setup.cfg, setup.py
     ├── ...
     └── src/
         └── mypkg/
@@ -190,8 +189,7 @@ flat-layout
 The package folder(s) are placed directly under the project root::
 
     project_root_directory
-    ├── pyproject.toml
-    ├── setup.cfg  # or setup.py
+    ├── pyproject.toml  # AND/OR setup.cfg, setup.py
     ├── ...
     └── mypkg/
         ├── __init__.py
@@ -240,8 +238,7 @@ A standalone module is placed directly under the project root, instead of
 inside a package folder::
 
     project_root_directory
-    ├── pyproject.toml
-    ├── setup.cfg  # or setup.py
+    ├── pyproject.toml  # AND/OR setup.cfg, setup.py
     ├── ...
     └── single_file_lib.py
 
@@ -293,7 +290,7 @@ then returns a list of ``str`` representing the packages it could find. To use
 it, consider the following directory::
 
     mypkg
-    ├── setup.cfg  # and/or setup.py, pyproject.toml
+    ├── pyproject.toml  # AND/OR setup.cfg, setup.py
     └── src
         ├── pkg1
         │   └── __init__.py
@@ -320,7 +317,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``:
         [options.packages.find]
         where = src
         include = pkg*
-        exclude = additional
+        # alternatively: `exclude = additional*`
 
     .. note::
         ``pkg`` does not contain an ``__init__.py`` file, therefore
@@ -334,8 +331,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``:
             # ...
             packages=find_packages(
                 where='src',
-                include=['pkg*'],
-                exclude=['additional'],
+                include=['pkg*'],  # alternatively: `exclude=['additional*']`
             ),
             package_dir={"": "src"}
             # ...
@@ -353,8 +349,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``:
 
         [tool.setuptools.packages.find]
         where = ["src"]
-        include = ["pkg*"]
-        exclude = ["additional"]
+        include = ["pkg*"]  # alternatively: `exclude = ["additional*"]`
         namespaces = false
 
     .. note::
@@ -412,7 +407,7 @@ Now, suppose you decide to package the ``foo`` part for distribution and start
 by creating a project directory organized as follows::
 
    foo
-   ├── setup.cfg  # and/or setup.py, pyproject.toml
+   ├── pyproject.toml  # AND/OR setup.cfg, setup.py
    └── src
        └── timmins
            └── foo
@@ -517,7 +512,7 @@ to `PEP 420 <https://www.python.org/dev/peps/pep-0420/>`_. It used to be more
 cumbersome to accomplish the same result. Historically, there were two methods
 to create namespace packages. One is the ``pkg_resources`` style supported by
 ``setuptools`` and the other one being ``pkgutils`` style offered by
-``pkgutils`` module in Python. Both are now considered deprecated despite the
+``pkgutils`` module in Python. Both are now considered *deprecated* despite the
 fact they still linger in many existing packages. These two differ in many
 subtle yet significant aspects and you can find out more on `Python packaging
 user guide <https://packaging.python.org/guides/packaging-namespace-packages/>`_.
@@ -557,7 +552,7 @@ And your directory should look like this
 .. code-block:: bash
 
    foo
-   ├── setup.cfg  # and/or setup.py, pyproject.toml
+   ├── pyproject.toml  # AND/OR setup.cfg, setup.py
    └── src
        └── timmins
            ├── __init__.py
@@ -577,7 +572,7 @@ file contains the following:
 
     __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
-The project layout remains the same and ``setup.cfg`` remains the same.
+The project layout remains the same and ``pyproject.toml/setup.cfg`` remains the same.
 
 
 ----