Merge branch 'master' into docs/setup.cfg-only

8 files changed, 189 insertions, 143 deletions

diff --git a/docs/build_meta.txt b/docs/build_meta.txt
new file mode 100644
index 00000000..ef9fb2ac
--- /dev/null
+++ b/docs/build_meta.txt
@@ -0,0 +1,89 @@
+=======================================
+Build System Support
+=======================================
+
+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
+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. 
+This interface makes it difficult to choose other packaging tools without an 
+overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it
+proved difficult to provide a reliable user experience across environments
+and history.
+
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
+rescue and specified a new standard to 
+package and distribute Python modules. Under PEP 517:
+
+    a ``pyproject.toml`` file is used to specify what program to use
+    for generating distribution. 
+
+    Then, two functions provided by the program, ``build_wheel(directory: str)`` 
+    and ``build_sdist(directory: str)`` create the distribution bundle at the 
+    specified ``directory``. The program is free to use its own configuration 
+    script or extend the ``.toml`` file. 
+
+    Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual
+    installation. If ``*.whl`` is available, ``pip`` will go ahead and copy
+    the files into ``site-packages`` directory. If not, ``pip`` will look at
+    ``pyproject.toml`` and decide what program to use to 'build from source' 
+    (the default is ``setuptools``)
+
+With this standard, switching between packaging tools becomes a lot easier. ``build_meta``
+implements ``setuptools``' build system support.
+
+How to use it?
+--------------
+
+Starting with a package that you want to distribute. You will need your source
+scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file::
+
+    ~/meowpkg/
+        pyproject.toml
+        setup.cfg
+        meowpkg/__init__.py
+
+The pyproject.toml file is required to specify the build system (i.e. what is 
+being used to package your scripts and install from source). To use it with 
+setuptools, the content would be::
+
+    [build-system]
+    requires = ["setuptools", "wheel"]
+    build-backend = "setuptools.build_meta" 
+
+Use ``setuptools``' `declarative config`_ to specify the package information::
+
+    [metadata]
+    name = meowpkg
+    version = 0.0.1
+    description = a package that meows
+    
+    [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::
+
+    $ pip install -q pep517
+    $ mkdir dist
+    $ python -m pep517.build .
+
+And now it's done! The ``.whl`` file  and ``.tar.gz`` can then be distributed 
+and installed::
+
+    dist/
+        meowpkg-0.0.1.whl
+        meowpkg-0.0.1.tar.gz
+
+    $ pip install dist/meowpkg-0.0.1.whl
+
+or::
+
+    $ pip install dist/meowpkg-0.0.1.tar.gz
diff --git a/docs/conf.py b/docs/conf.py
index cbd19fb4..b92b50cc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,23 +1,3 @@
-# -*- coding: utf-8 -*-
-#
-# Setuptools documentation build configuration file, created by
-# sphinx-quickstart on Fri Jul 17 14:22:37 2009.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
 import subprocess
 import sys
 import os
@@ -26,14 +6,12 @@ import os
 # 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, 'bootstrap.py'],
+    [sys.executable, '-m', 'bootstrap'],
     cwd=os.path.join(os.path.dirname(__file__), os.path.pardir),
 )
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration --
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['jaraco.packaging.sphinx', 'rst.linker']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -45,7 +23,8 @@ source_suffix = '.txt'
 # The master toctree document.
 master_doc = 'index'
 
-# A list of glob-style patterns that should be excluded when looking for source files.
+# A list of glob-style patterns that should be excluded
+# when looking for source files.
 exclude_patterns = ['requirements.txt']
 
 # List of directories, relative to source directory, that shouldn't be searched
@@ -55,7 +34,7 @@ exclude_trees = []
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output ---------------------------------------------------
+# -- 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'.
@@ -69,7 +48,10 @@ html_theme_path = ['_theme']
 html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {'index': ['relations.html', 'sourcelink.html', 'indexsidebar.html', 'searchbox.html']}
+html_sidebars = {
+    'index': [
+        'relations.html', 'sourcelink.html', 'indexsidebar.html',
+        'searchbox.html']}
 
 # If false, no module index is generated.
 html_use_modindex = False
@@ -77,14 +59,15 @@ html_use_modindex = False
 # If false, no index is generated.
 html_use_index = False
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- 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'),
-]
+# (source start file, target name, title, author,
+# documentclass [howto/manual]).
+latex_documents = [(
+    'index', 'Setuptools.tex', 'Setuptools Documentation',
+    'The fellowship of the packaging', 'manual',
+)]
 
 link_files = {
     '../CHANGES.rst': dict(
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
index d145fba1..0b4ae4d4 100644
--- a/docs/developer-guide.txt
+++ b/docs/developer-guide.txt
@@ -104,12 +104,8 @@ from the command line after pushing a new branch.
 Testing
 -------
 
-The primary tests are run using tox. To run the tests, first create the metadata
-needed to run the tests::
-
-    $ python bootstrap.py
-
-Then make sure you have tox installed, and invoke it::
+The primary tests are run using tox.  Make sure you have tox installed,
+and invoke it::
 
     $ tox
 
diff --git a/docs/history.txt b/docs/history.txt
index 385cfa7e..faf7adfe 100644
--- a/docs/history.txt
+++ b/docs/history.txt
@@ -12,7 +12,7 @@ Credits
 
 * The original design for the ``.egg`` format and the ``pkg_resources`` API was
   co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first
-  version of ``pkg_resources``, and supplied the OS X operating system version
+  version of ``pkg_resources``, and supplied the macOS operating system version
   compatibility algorithm.
 
 * Ian Bicking implemented many early "creature comfort" features of
diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt
index b887a923..71568c1a 100644
--- a/docs/pkg_resources.txt
+++ b/docs/pkg_resources.txt
@@ -1621,7 +1621,7 @@ Platform Utilities
 
 ``get_build_platform()``
     Return this platform's identifier string.  For Windows, the return value
-    is ``"win32"``, and for Mac OS X it is a string of the form
+    is ``"win32"``, and for macOS it is a string of the form
     ``"macosx-10.4-ppc"``.  All other platforms return the same uname-based
     string that the ``distutils.util.get_platform()`` function returns.
     This string is the minimum platform version required by distributions built
@@ -1641,7 +1641,7 @@ Platform Utilities
     considered a wildcard, and the platforms are therefore compatible.
     Likewise, if the platform strings are equal, they're also considered
     compatible, and ``True`` is returned.  Currently, the only non-equal
-    platform strings that are considered compatible are Mac OS X platform
+    platform strings that are considered compatible are macOS platform
     strings with the same hardware type (e.g. ``ppc``) and major version
     (e.g. ``10``) with the `provided` platform's minor version being less than
     or equal to the `required` platform's minor version.
@@ -1674,7 +1674,7 @@ File/Path Utilities
     the same filesystem location if they have equal ``normalized_path()``
     values.  Specifically, this is a shortcut for calling ``os.path.realpath``
     and ``os.path.normcase`` on `path`.  Unfortunately, on certain platforms
-    (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately
+    (notably Cygwin and macOS) the ``normcase`` function does not accurately
     reflect the platform's case-sensitivity, so there is always the possibility
     of two apparently-different paths being equal on such platforms.
 
diff --git a/docs/releases.txt b/docs/releases.txt
index 98ba39e8..35b415c2 100644
--- a/docs/releases.txt
+++ b/docs/releases.txt
@@ -3,39 +3,13 @@ Release Process
 ===============
 
 In order to allow for rapid, predictable releases, Setuptools uses a
-mechanical technique for releases, enacted by Travis following a
-successful build of a tagged release per
-`PyPI deployment <https://docs.travis-ci.com/user/deployment/pypi>`_.
-
-Prior to cutting a release, please use `towncrier`_ to update
-``CHANGES.rst`` to summarize the changes since the last release.
-To update the changelog:
-
-1. Install towncrier via ``pip install towncrier`` if not already installed.
-2. Preview the new ``CHANGES.rst`` entry by running
-   ``towncrier --draft --version {new.version.number}`` (enter the desired
-   version number for the next release).  If any changes are needed, make
-   them and generate a new preview until the output is acceptable.  Run
-   ``git add`` for any modified files.
-3. Run ``towncrier --version {new.version.number}`` to stage the changelog
-   updates in git.
-4. Verify that there are no remaining ``changelog.d/*.rst`` files.  If a
-   file was named incorrectly, it may be ignored by towncrier.
-5. Review the updated ``CHANGES.rst`` file.  If any changes are needed,
-   make the edits and stage them via ``git add CHANGES.rst``.
-
-Once the changelog edits are staged and ready to commit, cut a release by
-installing and running ``bump2version --allow-dirty {part}`` where ``part``
-is major, minor, or patch based on the scope of the changes in the
-release. Then, push the commits to the master branch::
-
-    $ git push origin master
-    $ git push --tags
-
-If tests pass, the release will be uploaded to PyPI (from the Python 3.6
-tests).
-
-.. _towncrier: https://pypi.org/project/towncrier/
+mechanical technique for releases, enacted on tagged commits by
+continuous integration.
+
+To finalize a release, run ``tox -e finalize``, review, then push
+the changes.
+
+If tests pass, the release will be uploaded to PyPI.
 
 Release Frequency
 -----------------
diff --git a/docs/requirements.txt b/docs/requirements.txt
index e82df49c..104d68fa 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,6 +1,7 @@
-sphinx!=1.8.0
-pygments-github-lexers==0.0.5
-rst.linker>=1.9
+# 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.txt b/docs/setuptools.txt
index e5663fc4..ec58b754 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -88,7 +88,7 @@ packages in the directory where the setup.py lives.  See the `Command
 Reference`_ section below to see what commands you can give to this setup
 script. For example, to produce a source distribution, simply invoke::
 
-    python setup.py sdist
+    setup.py sdist
 
 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
@@ -100,17 +100,17 @@ dependencies, and perhaps some data files and scripts::
         name="HelloWorld",
         version="0.1",
         packages=find_packages(),
-        scripts=['say_hello.py'],
+        scripts=["say_hello.py"],
 
         # Project uses reStructuredText, so ensure that the docutils get
         # installed or upgraded on the target machine
-        install_requires=['docutils>=0.3'],
+        install_requires=["docutils>=0.3"],
 
         package_data={
             # If any package contains *.txt or *.rst files, include them:
-            '': ['*.txt', '*.rst'],
-            # And include any *.msg files found in the 'hello' package, too:
-            'hello': ['*.msg'],
+            "": ["*.txt", "*.rst"],
+            # And include any *.msg files found in the "hello" package, too:
+            "hello": ["*.msg"],
         },
 
         # metadata to display on PyPI
@@ -125,7 +125,7 @@ dependencies, and perhaps some data files and scripts::
             "Source Code": "https://code.example.com/HelloWorld/",
         },
         classifiers=[
-            'License :: OSI Approved :: Python Software Foundation License'
+            "License :: OSI Approved :: Python Software Foundation License"
         ]
 
         # could also include long_description, download_url, etc.
@@ -207,11 +207,11 @@ but here are a few tips that will keep you out of trouble in the corner cases:
   to compare different version numbers::
 
     >>> from pkg_resources import parse_version
-    >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
+    >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
     True
-    >>> parse_version('2.1-rc2') < parse_version('2.1')
+    >>> parse_version("2.1-rc2") < parse_version("2.1")
     True
-    >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
+    >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
     True
 
 Once you've decided on a version numbering scheme for your project, you can
@@ -371,7 +371,7 @@ unless you need the associated ``setuptools`` feature.
     imported.  This argument is only useful if the project will be installed as
     a zipfile, and there is a need to have all of the listed resources be
     extracted to the filesystem *as a unit*.  Resources listed here
-    should be '/'-separated paths, relative to the source root, so to list a
+    should be "/"-separated paths, relative to the source root, so to list a
     resource ``foo.png`` in package ``bar.baz``, you would include the string
     ``bar/baz/foo.png`` in this argument.
 
@@ -413,7 +413,7 @@ the same
 directory as the setup script.  Some projects use a ``src`` or ``lib``
 directory as the root of their source tree, and those projects would of course
 use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``.  (And
-such projects also need something like ``package_dir={'':'src'}`` in their
+such projects also need something like ``package_dir={"": "src"}`` in their
 ``setup()`` arguments, but that's just a normal distutils thing.)
 
 Anyway, ``find_packages()`` walks the target directory, filtering by inclusion
@@ -480,7 +480,7 @@ top-level package called ``tests``! One way to avoid this problem is to use the
     setup(
         name="namespace.mypackage",
         version="0.1",
-        packages=find_namespace_packages(include=['namespace.*'])
+        packages=find_namespace_packages(include=["namespace.*"])
     )
 
 Another option is to use the "src" layout, where all package code is placed in
@@ -500,8 +500,8 @@ With this layout, the package directory is specified as ``src``, as such::
 
     setup(name="namespace.mypackage",
           version="0.1",
-          package_dir={'': 'src'},
-          packages=find_namespace_packages(where='src'))
+          package_dir={"": "src"},
+          packages=find_namespace_packages(where="src"))
 
 .. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 
@@ -526,12 +526,12 @@ script called ``baz``, you might do something like this::
     setup(
         # other arguments here...
         entry_points={
-            'console_scripts': [
-                'foo = my_package.some_module:main_func',
-                'bar = other_module:some_func',
+            "console_scripts": [
+                "foo = my_package.some_module:main_func",
+                "bar = other_module:some_func",
             ],
-            'gui_scripts': [
-                'baz = my_package_gui:start_func',
+            "gui_scripts": [
+                "baz = my_package_gui:start_func",
             ]
         }
     )
@@ -560,6 +560,8 @@ Services and Plugins`_.
 "Eggsecutable" Scripts
 ----------------------
 
+.. deprecated:: 45.3.0
+
 Occasionally, there are situations where it's desirable to make an ``.egg``
 file directly executable.  You can do this by including an entry point such
 as the following::
@@ -567,8 +569,8 @@ as the following::
     setup(
         # other arguments here...
         entry_points={
-            'setuptools.installation': [
-                'eggsecutable = my_package.some_module:main_func',
+            "setuptools.installation": [
+                "eggsecutable = my_package.some_module:main_func",
             ]
         }
     )
@@ -741,8 +743,8 @@ For example, let's say that Project A offers optional PDF and reST support::
         name="Project-A",
         ...
         extras_require={
-            'PDF':  ["ReportLab>=1.2", "RXP"],
-            'reST': ["docutils>=0.3"],
+            "PDF":  ["ReportLab>=1.2", "RXP"],
+            "reST": ["docutils>=0.3"],
         }
     )
 
@@ -763,9 +765,9 @@ declare it like this, so that the "PDF" requirements are only resolved if the
         name="Project-A",
         ...
         entry_points={
-            'console_scripts': [
-                'rst2pdf = project_a.tools.pdfgen [PDF]',
-                'rst2html = project_a.tools.htmlgen',
+            "console_scripts": [
+                "rst2pdf = project_a.tools.pdfgen [PDF]",
+                "rst2html = project_a.tools.htmlgen",
                 # more script entry points ...
             ],
         }
@@ -801,8 +803,8 @@ setup to this::
         name="Project-A",
         ...
         extras_require={
-            'PDF':  [],
-            'reST': ["docutils>=0.3"],
+            "PDF":  [],
+            "reST": ["docutils>=0.3"],
         }
     )
 
@@ -829,8 +831,8 @@ For example, here is a project that uses the ``enum`` module and ``pywin32``::
         name="Project",
         ...
         install_requires=[
-            'enum34;python_version<"3.4"',
-            'pywin32 >= 1.0;platform_system=="Windows"'
+            "enum34;python_version<'3.4'",
+            "pywin32 >= 1.0;platform_system=='Windows'"
         ]
     )
 
@@ -878,9 +880,9 @@ e.g.::
         ...
         package_data={
             # If any package contains *.txt or *.rst files, include them:
-            '': ['*.txt', '*.rst'],
-            # And include any *.msg files found in the 'hello' package, too:
-            'hello': ['*.msg'],
+            "": ["*.txt", "*.rst"],
+            # And include any *.msg files found in the "hello" package, too:
+            "hello": ["*.msg"],
         }
     )
 
@@ -903,15 +905,15 @@ The setuptools setup file might look like this::
     from setuptools import setup, find_packages
     setup(
         ...
-        packages=find_packages('src'),  # include all packages under src
-        package_dir={'':'src'},   # tell distutils packages are under src
+        packages=find_packages("src"),  # include all packages under src
+        package_dir={"": "src"},   # tell distutils packages are under src
 
         package_data={
             # If any package contains *.txt files, include them:
-            '': ['*.txt'],
-            # And include any *.dat files found in the 'data' subdirectory
-            # of the 'mypkg' package, also:
-            'mypkg': ['data/*.dat'],
+            "": ["*.txt"],
+            # And include any *.dat files found in the "data" subdirectory
+            # of the "mypkg" package, also:
+            "mypkg": ["data/*.dat"],
         }
     )
 
@@ -926,7 +928,7 @@ converts slashes to appropriate platform-specific separators at build time.
 
 If datafiles are contained in a subdirectory of a package that isn't a package
 itself (no ``__init__.py``), then the subdirectory names (or ``*``) are required
-in the ``package_data`` argument (as shown above with ``'data/*.dat'``).
+in the ``package_data`` argument (as shown above with ``"data/*.dat"``).
 
 When building an ``sdist``, the datafiles are also drawn from the
 ``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if
@@ -939,7 +941,7 @@ python.org website.  If using the setuptools-specific ``include_package_data``
 argument, files specified by ``package_data`` will *not* be automatically
 added to the manifest unless they are listed in the MANIFEST.in file.)
 
-__ http://docs.python.org/dist/node11.html
+__ https://docs.python.org/3/distutils/setupscript.html#installing-package-data
 
 Sometimes, the ``include_package_data`` or ``package_data`` options alone
 aren't sufficient to precisely define what files you want included.  For
@@ -951,18 +953,18 @@ to do things like this::
     from setuptools import setup, find_packages
     setup(
         ...
-        packages=find_packages('src'),  # include all packages under src
-        package_dir={'':'src'},   # tell distutils packages are under src
+        packages=find_packages("src"),  # include all packages under src
+        package_dir={"": "src"},   # tell distutils packages are under src
 
         include_package_data=True,    # include everything in source control
 
         # ...but exclude README.txt from all packages
-        exclude_package_data={'': ['README.txt']},
+        exclude_package_data={"": ["README.txt"]},
     )
 
 The ``exclude_package_data`` option is a dictionary mapping package names to
 lists of wildcard patterns, just like the ``package_data`` option.  And, just
-as with that option, a key of ``''`` will apply the given pattern(s) to all
+as with that option, a key of ``""`` will apply the given pattern(s) to all
 packages.  However, any files that match these patterns will be *excluded*
 from installation, even if they were listed in ``package_data`` or were
 included as a result of using ``include_package_data``.
@@ -1096,12 +1098,12 @@ for our hypothetical blogging tool::
 
     setup(
         # ...
-        entry_points={'blogtool.parsers': '.rst = some_module:SomeClass'}
+        entry_points={"blogtool.parsers": ".rst = some_module:SomeClass"}
     )
 
     setup(
         # ...
-        entry_points={'blogtool.parsers': ['.rst = some_module:a_func']}
+        entry_points={"blogtool.parsers": [".rst = some_module:a_func"]}
     )
 
     setup(
@@ -1220,7 +1222,7 @@ Before you begin, make sure you have the latest versions of setuptools and wheel
 To build a setuptools project, run this command from the same directory where
 setup.py is located::
 
-    python3 setup.py sdist bdist_wheel
+    setup.py sdist bdist_wheel
 
 This will generate distribution archives in the `dist` directory.
 
@@ -1309,7 +1311,7 @@ participates in.  For example, the ZopeInterface project might do this::
 
     setup(
         # ...
-        namespace_packages=['zope']
+        namespace_packages=["zope"]
     )
 
 because it contains a ``zope.interface`` package that lives in the ``zope``
@@ -1327,7 +1329,7 @@ packages' ``__init__.py`` files (and the ``__init__.py`` of any parent
 packages), in a normal Python package layout.  These ``__init__.py`` files
 *must* contain the line::
 
-    __import__('pkg_resources').declare_namespace(__name__)
+    __import__("pkg_resources").declare_namespace(__name__)
 
 This code ensures that the namespace package machinery is operating and that
 the current package is registered as a namespace package.
@@ -1410,7 +1412,7 @@ pattern.  So, you can use a command line like::
 
     setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
 
-to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
+to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the
 most recent Subversion revision that affected the source tree), and then
 delete any egg files from the distribution directory except for the three
 that were built most recently.
@@ -1469,7 +1471,7 @@ tagging the release, so the trunk will still produce development snapshots.
 Alternately, if you are not branching for releases, you can override the
 default version options on the command line, using something like::
 
-    python setup.py egg_info -Db "" sdist bdist_egg
+    setup.py egg_info -Db "" sdist bdist_egg
 
 The first part of this command (``egg_info -Db ""``) will override the
 configured tag information, before creating source and binary eggs. Thus, these
@@ -1479,11 +1481,11 @@ build designation string.
 Of course, if you will be doing this a lot, you may wish to create a personal
 alias for this operation, e.g.::
 
-    python setup.py alias -u release egg_info -Db ""
+    setup.py alias -u release egg_info -Db ""
 
 You can then use it like this::
 
-    python setup.py release sdist bdist_egg
+    setup.py release sdist bdist_egg
 
 Or of course you can create more elaborate aliases that do all of the above.
 See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
@@ -1500,7 +1502,7 @@ To ensure Cython is available, include Cython in the build-requires section
 of your pyproject.toml::
 
     [build-system]
-    requires=[..., 'cython']
+    requires=[..., "cython"]
 
 Built with pip 10 or later, that declaration is sufficient to include Cython
 in the build. For broader compatibility, declare the dependency in your
@@ -1800,7 +1802,7 @@ to support "daily builds" or "snapshot" releases.  It is run automatically by
 the ``sdist``, ``bdist_egg``, ``develop``, and ``test`` commands in order to
 update the project's metadata, but you can also specify it explicitly in order
 to temporarily change the project's version string while executing other
-commands.  (It also generates the``.egg-info/SOURCES.txt`` manifest file, which
+commands.  (It also generates the ``.egg-info/SOURCES.txt`` manifest file, which
 is used when you are building source distributions.)
 
 In addition to writing the core egg metadata defined by ``setuptools`` and
@@ -1848,7 +1850,7 @@ binary distributions of your project, you should first make sure that you know
 how the resulting version numbers will be interpreted by automated tools
 like pip.  See the section above on `Specifying Your Project's Version`_ for an
 explanation of pre- and post-release tags, as well as tips on how to choose and
-verify a versioning scheme for your your project.)
+verify a versioning scheme for your project.)
 
 For advanced uses, there is one other option that can be set, to change the
 location of the project's ``.egg-info`` directory.  Commands that need to find
@@ -1873,12 +1875,12 @@ Other ``egg_info`` Options
 
 Creating a dated "nightly build" snapshot egg::
 
-    python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
+    setup.py egg_info --tag-date --tag-build=DEV bdist_egg
 
 Creating a release with no version tags, even if some default tags are
 specified in ``setup.cfg``::
 
-    python setup.py egg_info -RDb "" sdist bdist_egg
+    setup.py egg_info -RDb "" sdist bdist_egg
 
 (Notice that ``egg_info`` must always appear on the command line *before* any
 commands that you want the version changes to apply to.)
@@ -2104,8 +2106,9 @@ Configuring setup() using setup.cfg files
 .. note:: New in 30.3.0 (8 Dec 2016).
 
 .. important::
-    A ``setup.py`` file containing a ``setup()`` function call is still
-    required even if your configuration resides in ``setup.cfg``.
+    If compatibility with legacy builds (i.e. those not using the :pep:`517`
+    build API) is desired, a ``setup.py`` file containing a ``setup()`` function
+    call is still required even if your configuration resides in ``setup.cfg``.
 
 ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
 to define a package’s metadata and other options that are normally supplied
@@ -2394,7 +2397,7 @@ parsing ``metadata`` and ``options`` sections into a dictionary.
 
     from setuptools.config import read_configuration
 
-    conf_dict = read_configuration('/home/user/dev/package/setup.cfg')
+    conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
 
 
 By default, ``read_configuration()`` will read only the file provided
@@ -2574,7 +2577,7 @@ a file.  Here's what the writer utility looks like::
         argname = os.path.splitext(basename)[0]
         value = getattr(cmd.distribution, argname, None)
         if value is not None:
-            value = '\n'.join(value) + '\n'
+            value = "\n".join(value) + "\n"
         cmd.write_or_delete_file(argname, filename, value)
 
 As you can see, ``egg_info.writers`` entry points must be a function taking