Merge branch 'main' into feature/distutils-docsfeature/distutils-docs

13 files changed, 323 insertions, 283 deletions

diff --git a/docs/_templates/tidelift-sidebar.html b/docs/_templates/tidelift-sidebar.html
new file mode 100644
index 00000000..ce48f46b
--- /dev/null
+++ b/docs/_templates/tidelift-sidebar.html
@@ -0,0 +1,6 @@
+<h3 class="donation">For Enterprise</h3>
+
+<p>
+Professionally-supported {{ project }} is available with the
+<a href="https://tidelift.com/subscription/pkg/pypi-{{ project }}?utm_source=pypi-{{ project }}&utm_medium=referral">Tidelift Subscription</a>.
+</p>
diff --git a/docs/build_meta.rst b/docs/build_meta.rst
index c36e2bab..2ad5ae26 100644
--- a/docs/build_meta.rst
+++ b/docs/build_meta.rst
@@ -7,7 +7,7 @@ What is it?
 
 Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
 
-The traditional ``setuptools`` way of packgaging Python modules
+The traditional ``setuptools`` way of packaging Python modules
 uses a ``setup()`` function within the ``setup.py`` script. Commands such as
 ``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a 
 distribution bundle and ``python setup.py install`` installs the distribution. 
@@ -67,14 +67,11 @@ specify the package information::
     [options]
     packages = find:
 
-Now generate the distribution. Although the PyPA is still working to
-`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
-to build packages, the `pep517 package <https://pypi.org/project/pep517>`_
-provides this functionality. To build the package::
+Now generate the distribution. To build the package, use
+`PyPA build <https://pypa-build.readthedocs.io/en/latest/>`_::
 
-    $ pip install -q pep517
-    $ mkdir dist
-    $ python -m pep517.build .
+    $ pip install -q build
+    $ python -m build
 
 And now it's done! The ``.whl`` file  and ``.tar.gz`` can then be distributed 
 and installed::
diff --git a/docs/conf.py b/docs/conf.py
index de9fe3f8..65078c96 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,81 +1,6 @@
-import subprocess
-import sys
-import os
+extensions = ['sphinx.ext.autodoc', 'jaraco.packaging.sphinx', 'rst.linker']
 
-
-# hack to run the bootstrap script so that jaraco.packaging.sphinx
-# can invoke setup.py
-'READTHEDOCS' in os.environ and subprocess.check_call(
-    [sys.executable, '-m', 'bootstrap'],
-    cwd=os.path.join(os.path.dirname(__file__), os.path.pardir),
-)
-
-# -- Project information -----------------------------------------------------
-
-github_url = 'https://github.com'
-github_sponsors_url = f'{github_url}/sponsors'
-
-# -- General configuration --
-
-extensions = [
-    'sphinx.ext.extlinks',  # allows to create custom roles easily
-    'sphinx.ext.intersphinx',  # allows interlinking external docs sites
-    'jaraco.packaging.sphinx',
-    'rst.linker',
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The master toctree document.
-master_doc = 'index'
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# -- Options for extlinks extension ---------------------------------------
-extlinks = {
-    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
-}
-
-# -- Options for HTML output --
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'nature'
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_theme']
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-    'index': [
-        'relations.html', 'sourcelink.html', 'indexsidebar.html',
-        'searchbox.html']}
-
-# If false, no module index is generated.
-html_use_modindex = False
-
-# If false, no index is generated.
-html_use_index = False
-
-# -- Options for LaTeX output --
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author,
-# documentclass [howto/manual]).
-latex_documents = [(
-    'index', 'Setuptools.tex', 'Setuptools Documentation',
-    'The fellowship of the packaging', 'manual',
-)]
+master_doc = "index"
 
 link_files = {
     '../CHANGES.rst': dict(
@@ -148,10 +73,38 @@ link_files = {
     ),
 }
 
+intersphinx_mapping = {
+    'pypa-build': ('https://pypa-build.readthedocs.io/en/latest/', None)
+}
+
+# Add support for linking usernames
+github_url = 'https://github.com'
+github_sponsors_url = f'{github_url}/sponsors'
+extlinks = {
+    'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
+}
+extensions += ['sphinx.ext.extlinks', 'sphinx.ext.intersphinx']
 
 # Be strict about any broken references:
 nitpicky = True
 
+# Ref: https://github.com/python-attrs/attrs/pull/571/files\
+#      #diff-85987f48f1258d9ee486e3191495582dR82
+default_role = 'any'
+
+# Custom sidebar templates, maps document names to template names.
+html_theme = 'alabaster'
+templates_path = ['_templates']
+html_sidebars = {'index': ['tidelift-sidebar.html']}
+
+# Add support for inline tabs
+extensions += ['sphinx_inline_tabs']
+
+## Support for distutils
+
+# allow interlinking external docs sites
+extensions += ['sphinx.ext.intersphinx'],  
+
 # Ref: https://stackoverflow.com/a/30624034/595220
 nitpick_ignore = [
     ('c:func', 'SHGetSpecialFolderPath'),  # ref to MS docs
@@ -188,12 +141,6 @@ nitpick_ignore = [
     ('py:mod', 'docutils'),  # there's no Sphinx site documenting this
 ]
 
-
-# Ref: https://github.com/python-attrs/attrs/pull/571/files\
-#      #diff-85987f48f1258d9ee486e3191495582dR82
-default_role = 'any'
-
-
 # Allow linking objects on other Sphinx sites seamlessly:
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
diff --git a/docs/pkg_resources.rst b/docs/pkg_resources.rst
index 364e2183..994bea6f 100644
--- a/docs/pkg_resources.rst
+++ b/docs/pkg_resources.rst
@@ -10,6 +10,13 @@ eggs, support for merging packages that have separately-distributed modules or
 subpackages, and APIs for managing Python's current "working set" of active
 packages.
 
+Use of ``pkg_resources`` is discouraged in favor of
+`importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_,
+`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_,
+and their backports (`resources <https://pypi.org/project/importlib_resources>`_,
+`metadata <https://pypi.org/project/importlib_metadata>`_).
+Please consider using those libraries instead of pkg_resources.
+
 
 .. contents:: **Table of Contents**
 
@@ -703,7 +710,7 @@ entry point group and look for entry points named "pre_process" and
 To advertise an entry point, a project needs to use ``setuptools`` and provide
 an ``entry_points`` argument to ``setup()`` in its setup script, so that the
 entry points will be included in the distribution's metadata.  For more
-details, see the [``setuptools`` documentation](https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins).
+details, see :ref:`Advertising Behavior<dynamic discovery of services and plugins>`.
 
 Each project distribution can advertise at most one entry point of a given
 name within the same entry point group.  For example, a distutils extension
@@ -1939,4 +1946,3 @@ History
 
 0.3a1
  * Initial release.
-
diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst
index 03ce9fa2..619b2d14 100644
--- a/docs/references/keywords.rst
+++ b/docs/references/keywords.rst
@@ -76,6 +76,17 @@ Keywords
 ``license``
     A string specifying the license of the package.
 
+``license_file``
+
+    .. warning::
+        ``license_file`` is deprecated. Use ``license_files`` instead.
+
+``license_files``
+
+    A list of glob patterns for license related files that should be included.
+    If neither ``license_file`` nor ``license_files`` is specified, this option
+    defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``.
+
 ``keywords``
     A list of strings or a comma-separated string providing descriptive
     meta-data. See: `PEP 0314`_.
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index 104d68fa..00000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-# keep these in sync with setup.cfg
-sphinx
-jaraco.packaging>=6.1
-rst.linker>=1.9
-pygments-github-lexers==0.0.5
-
-setuptools>=34
diff --git a/docs/setuptools.rst b/docs/setuptools.rst
index 1000a0ce..541bec51 100644
--- a/docs/setuptools.rst
+++ b/docs/setuptools.rst
@@ -54,7 +54,7 @@ Feature Highlights:
 Developer's Guide
 -----------------
 
-
+The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.
 
 
 
@@ -157,7 +157,7 @@ To use this feature:
       ]
       build-backend = "setuptools.build_meta"
 
-* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``pep517``.
+* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.
 
   .. warning::
 
diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst
index bc66869b..7c97ca1c 100644
--- a/docs/userguide/declarative_config.rst
+++ b/docs/userguide/declarative_config.rst
@@ -184,7 +184,7 @@ maintainer_email                maintainer-email   str
 classifiers                     classifier         file:, list-comma
 license                                            str
 license_file                                       str
-license_files                                      list-comma
+license_files                                      list-comma         42.0.0
 description                     summary            file:, str
 long_description                long-description   file:, str
 long_description_content_type                      str                38.6.0
@@ -243,6 +243,19 @@ data_files               dict                                 40.6.0
 
     **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
 
+
 Notes:
 1. In the ``package_data`` section, a key named with a single asterisk (``*``)
 refers to all packages, in lieu of the empty string used in ``setup.py``.
+
+2. In the ``extras_require`` section, values are parsed as ``list-semi``. This implies that in
+order to include markers, they **must** be *dangling*:
+
+.. code-block:: ini
+
+    [options.extras_require]
+    rest = docutils>=0.3; pack ==1.1, ==1.3
+    pdf =
+      ReportLab>=1.2
+      RXP
+      importlib-metadata; python_version < "3.8"
diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index 354a9f8c..188083e0 100644
--- a/docs/userguide/dependency_management.rst
+++ b/docs/userguide/dependency_management.rst
@@ -3,7 +3,7 @@ Dependencies Management in Setuptools
 =====================================
 
 There are three types of dependency styles offered by setuptools:
-1) build system requirement, required dependency and 3) optional
+1) build system requirement, 2) required dependency and 3) optional
 dependency.
 
 .. Note::
@@ -19,8 +19,8 @@ Build system requirement
 Package requirement
 -------------------
 After organizing all the scripts and files and getting ready for packaging,
-there needs to be a way to tell Python what programs it need to actually
-do the packgaging (in our case, ``setuptools`` of course). Usually,
+there needs to be a way to tell Python what programs it needs to actually
+do the packaging (in our case, ``setuptools`` of course). Usually,
 you also need the ``wheel`` package as well since it is recommended that you
 upload a ``.whl`` file to PyPI alongside your ``.tar.gz`` file. Unlike the
 other two types of dependency keyword, this one is specified in your
@@ -47,32 +47,36 @@ Declaring required dependency
 This is where a package declares its core dependencies, without which it won't
 be able to run. ``setuptools`` support automatically download and install
 these dependencies when the package is installed. Although there is more
-finess to it, let's start with a simple example.
+finesse to it, let's start with a simple example.
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    #...
-    install_requires =
-        docutils
-        BazSpam ==1.1
+    .. code-block:: ini
+
+        [options]
+        #...
+        install_requires =
+            docutils
+            BazSpam ==1.1
+
+.. tab:: setup.py
 
-.. code-block:: python
+    .. code-block:: python
 
-    setup(
-        #...,
-        install_requires = [
-            'docutils',
-            'BazSpam ==1.1'
-        ]
-    )
+        setup(
+            #...,
+            install_requires = [
+                'docutils',
+                'BazSpam ==1.1'
+            ]
+        )
 
 
 When your project is installed (e.g. using pip), all of the dependencies not
 already installed will be located (via PyPI), downloaded, built (if necessary),
 and installed and 2) Any scripts in your project will be installed with wrappers
 that verify the availability of the specified dependencies at runtime.
-    
+
 
 Platform specific dependencies
 ------------------------------
@@ -82,41 +86,49 @@ specific dependencies. For example, the ``enum`` package was added in Python
 3.4, therefore, package that depends on it can elect to install it only when
 the Python version is older than 3.4. To accomplish this
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    #...
-    install_requires =
-        enum34;python_version<'3.4'
+    .. code-block:: ini
 
-.. code-block:: python
-
-    setup(
+        [options]
         #...
-        install_requires=[
-            "enum34;python_version<'3.4'",]
-    )
+        install_requires =
+            enum34;python_version<'3.4'
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            install_requires=[
+                "enum34;python_version<'3.4'",]
+        )
 
 Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
 and only install it if the user is using a Windows operating system:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    install_requires =
-        enum34;python_version<'3.4'
-        pywin32 >= 1.0;platform_system=='Windows'
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        install_requires=[
-            "enum34;python_version<'3.4'",
-            "pywin32 >= 1.0;platform_system=='Windows'"
-            ]
-    )
+        install_requires =
+            enum34;python_version<'3.4'
+            pywin32 >= 1.0;platform_system=='Windows'
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            install_requires=[
+                "enum34;python_version<'3.4'",
+                "pywin32 >= 1.0;platform_system=='Windows'"
+                ]
+        )
 
 The environmental markers that may be used for testing platform types are
 detailed in `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_.
@@ -181,20 +193,24 @@ The ``dependency_links`` option takes the form of a list of URL strings.  For
 example, this will cause a search of the specified page for eggs or source
 distributions, if the package's dependencies aren't already installed:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    dependency_links = http://peak.telecommunity.com/snapshots/
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        dependency_links=[
-            "http://peak.telecommunity.com/snapshots/"
-        ],
-    )
+        dependency_links = http://peak.telecommunity.com/snapshots/
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            dependency_links=[
+                "http://peak.telecommunity.com/snapshots/"
+            ],
+        )
 
 
 Optional dependencies
@@ -202,7 +218,7 @@ Optional dependencies
 Setuptools allows you to declare dependencies that only get installed under
 specific circumstances. These dependencies are specified with ``extras_require``
 keyword and are only installed if another package depends on it (either
-directly or indirectly) This makes it convenient to declare dependencies for 
+directly or indirectly) This makes it convenient to declare dependencies for
 ancillary functions such as "tests" and "docs".
 
 .. note::
@@ -211,24 +227,28 @@ ancillary functions such as "tests" and "docs".
 For example, Package-A offers optional PDF support and requires two other
 dependencies for it to work:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Package-A
+    .. code-block:: ini
 
-    [options.extras_require]
-    PDF = ReportLab>=1.2; RXP
+        [metadata]
+        name = Package-A
 
+        [options.extras_require]
+        PDF = ReportLab>=1.2; RXP
 
-.. code-block:: python
 
-    setup(
-        name="Project-A",
-        #...
-        extras_require={
-            "PDF":  ["ReportLab>=1.2", "RXP"],
-        }
-    )
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            name="Project-A",
+            #...
+            extras_require={
+                "PDF":  ["ReportLab>=1.2", "RXP"],
+            }
+        )
 
 The name ``PDF`` is an arbitary identifier of such a list of dependencies, to
 which other components can refer and have them installed. There are two common
@@ -236,57 +256,69 @@ use cases.
 
 First is the console_scripts entry point:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Project A
-    #...
+    .. code-block:: ini
 
-    [options]
-    #...
-    entry_points=
-        [console_scripts]
-        rst2pdf = project_a.tools.pdfgen [PDF]
-        rst2html = project_a.tools.htmlgen
-
-.. code-block:: python
-
-    setup(
-        name = "Project-A"
-        #...,
-        entry_points={
-            "console_scripts": [
-                "rst2pdf = project_a.tools.pdfgen [PDF]",
-                "rst2html = project_a.tools.htmlgen",
-            ],
-        }
-    )
+        [metadata]
+        name = Project A
+        #...
 
-When the script ``rst2pdf`` is run, it will trigger the installation of
-the two dependencies ``PDF`` maps to.
+        [options]
+        #...
+        entry_points=
+            [console_scripts]
+            rst2pdf = project_a.tools.pdfgen [PDF]
+            rst2html = project_a.tools.htmlgen
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            name = "Project-A"
+            #...,
+            entry_points={
+                "console_scripts": [
+                    "rst2pdf = project_a.tools.pdfgen [PDF]",
+                    "rst2html = project_a.tools.htmlgen",
+                ],
+            }
+        )
+
+This syntax indicates that the entry point (in this case a console script)
+is only valid when the PDF extra is installed. It is up to the installer
+to determine how to handle the situation where PDF was not indicated
+(e.g. omit the console script, provide a warning when attempting to load
+the entry point, assume the extras are present and let the implementation
+fail later).
 
 The second use case is that other package can use this "extra" for their
 own dependencies. For example, if "Project-B" needs "project A" with PDF support
 installed, it might declare the dependency like this:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Project-B
-    #...
+    .. code-block:: ini
 
-    [options]
-    #...
-    install_requires =
-        Project-A[PDF]
+        [metadata]
+        name = Project-B
+        #...
+
+        [options]
+        #...
+        install_requires =
+            Project-A[PDF]
+
+.. tab:: setup.py
 
-.. code-block:: python
+    .. code-block:: python
 
-    setup(
-        name="Project-B",
-        install_requires=["Project-A[PDF]"],
-        ...
-    )
+        setup(
+            name="Project-B",
+            install_requires=["Project-A[PDF]"],
+            ...
+        )
 
 This will cause ReportLab to be installed along with project A, if project B is
 installed -- even if project A was already installed.  In this way, a project
diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst
index bce724a7..3c477ec1 100644
--- a/docs/userguide/development_mode.rst
+++ b/docs/userguide/development_mode.rst
@@ -3,9 +3,9 @@
 
 Under normal circumstances, the ``distutils`` assume that you are going to
 build a distribution of your project, not use it in its "raw" or "unbuilt"
-form.  If you were to use the ``distutils`` that way, you would have to rebuild
-and reinstall your project every time you made a change to it during
-development.
+form.  However, if you were to use the ``distutils`` to build a distribution,
+you would have to rebuild and reinstall your project every time you made a
+change to it during development.
 
 Another problem that sometimes comes up with the ``distutils`` is that you may
 need to do development on two related projects at the same time.  You may need
diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst
index edab4465..63d30a48 100644
--- a/docs/userguide/entry_point.rst
+++ b/docs/userguide/entry_point.rst
@@ -28,7 +28,7 @@ with ``__init__.py`` as:
 
 .. code-block:: python
 
-    def helloworld():
+    def hello_world():
         print("Hello world")
 
 and ``__main__.py`` providing a hook:
@@ -64,7 +64,7 @@ After installing the package, a user may invoke that function by simply calling
 
 The syntax for entry points is specified as follows:
 
-.. code-block::
+.. code-block:: ini
 
     <name> = [<package>.[<subpackage>.]]<module>[:<object>.<object>]
 
diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
index de4ef668..0a8070ae 100644
--- a/docs/userguide/package_discovery.rst
+++ b/docs/userguide/package_discovery.rst
@@ -19,36 +19,44 @@ Package Discovery and Namespace Package
 support for namespace package. Normally, you would specify the package to be
 included manually in the following manner:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    packages =
-        mypkg1
-        mypkg2
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        packages = ['mypkg1', 'mypkg2']
-    )
+        packages =
+            mypkg1
+            mypkg2
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            packages = ['mypkg1', 'mypkg2']
+        )
 
 This can get tiresome reallly quickly. To speed things up, we introduce two
 functions provided by setuptools:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    packages = find:
-    #or
-    packages = find_namespace:
+    .. code-block:: ini
 
-.. code-block:: python
+        [options]
+        packages = find:
+        #or
+        packages = find_namespace:
+
+.. tab:: setup.py
 
-    from setuptools import find_packages
-    #or
-    from setuptools import find_namespace_packages
+    .. code-block:: python
+
+        from setuptools import find_packages
+        #or
+        from setuptools import find_namespace_packages
 
 
 Using ``find:`` or ``find_packages``
@@ -71,30 +79,34 @@ it, consider the following directory
 To have your setup.cfg or setup.py to automatically include packages found
 in ``src`` that starts with the name ``pkg`` and not ``additional``:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    packages = find:
-    package_dir =
-        =src
+    .. code-block:: ini
 
-    [options.packages.find]
-    where = src
-    include = pkg*
-    exclude = additional
+        [options]
+        packages = find:
+        package_dir =
+            =src
 
-.. code-block:: python
+        [options.packages.find]
+        where = src
+        include = pkg*
+        exclude = additional
 
-    setup(
-        #...
-        packages = find_packages(
-            where = 'src',
-            include = ['pkg*',],
-            exclude = ['additional',]
-        ),
-        package_dir = {"":"src"}
-        #...
-    )
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            packages = find_packages(
+                where = 'src',
+                include = ['pkg*',],
+                exclude = ['additional',]
+            ),
+            package_dir = {"":"src"}
+            #...
+        )
 
 
 .. _Namespace Packages:
@@ -144,7 +156,7 @@ to use ``find_namespace:``:
         =src
     packages = find_namespace:
 
-    [options.packages.find_namespace]
+    [options.packages.find]
     where = src
 
 When you install the zipped distribution, ``timmins.foo`` would become
@@ -195,17 +207,21 @@ following:
 
 And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    namespace_packages = timmins
+    .. code-block:: ini
 
-.. code-block:: python
+        [options]
+        namespace_packages = timmins
+
+.. tab:: setup.py
+
+    .. code-block:: python
 
-    setup(
-        # ...
-        namespace_packages = ['timmins']
-    )
+        setup(
+            # ...
+            namespace_packages = ['timmins']
+        )
 
 And your directory should look like this
 
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 697087ed..2807f59b 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -21,7 +21,7 @@ the backend (build system) it wants to use. The distribution can then
 be generated with whatever tools that provides a ``build sdist``-alike
 functionality. While this may appear cumbersome, given the added pieces,
 it in fact tremendously enhances the portability of your package. The
-change is driven under :pep:`517 <517#build-requirements>`. To learn more about Python packaging in general,
+change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general,
 navigate to the `bottom <Resources on python packaging>`_ of this page.
 
 
@@ -37,33 +37,52 @@ package your project:
     requires = ["setuptools", "wheel"]
     build-backend = "setuptools.build_meta"
 
-Then, you will need a ``setup.cfg`` to specify your package information,
-such as metadata, contents, dependencies, etc. Here we demonstrate the minimum
+Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package
+information, such as metadata, contents, dependencies, etc. Here we demonstrate
+the minimum
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = "mypackage"
-    version = 0.0.1
+    .. code-block:: ini
 
-    [options]
-    packages = "mypackage"
-    install_requires =
-      requests
-      importlib; python_version == "2.6"
+        [metadata]
+        name = mypackage
+        version = 0.0.1
+
+        [options]
+        packages = mypackage
+        install_requires =
+        requests
+        importlib; python_version == "2.6"
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        from setuptools import setup
+
+        setup(
+            name='mypackage',
+            version='0.0.1',
+            packages=['mypackage'],
+            install_requires=[
+                'requests',
+                'importlib; python_version == "2.6"',
+            ],
+        )
 
 This is what your project would look like::
 
     ~/mypackage/
         pyproject.toml
-        setup.cfg
+        setup.cfg # or setup.py
         mypackage/__init__.py
 
-Then, you need an installer, such as `pep517 <https://pypi.org/project/pep517/>`_
-which you can obtain via ``pip install pep517``. After downloading it, invoke
-the installer::
+Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>`
+which you can obtain via ``pip install build``. After downloading it, invoke
+the builder::
 
-    python -m pep517.build
+    python -m build
 
 You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl``
 file in the ``dist`` directory), which you can upload to PyPI!
@@ -71,7 +90,7 @@ file in the ``dist`` directory), which you can upload to PyPI!
 Of course, before you release your project to PyPI, you'll want to add a bit
 more information to your setup script to help people find or learn about your
 project.  And maybe your project will have grown by then to include a few
-dependencies, and perhaps some data files and scripts. In the next few section,
+dependencies, and perhaps some data files and scripts. In the next few sections,
 we will walk through those additional but essential information you need
 to specify to properly package your project.