Merge branch 'master' into fix_889_and_non-ascii_in_setup.cfg_take_2

14 files changed, 585 insertions, 925 deletions

diff --git a/docs/_templates/indexsidebar.html b/docs/_templates/indexsidebar.html
index 3b127602..b8c6148e 100644
--- a/docs/_templates/indexsidebar.html
+++ b/docs/_templates/indexsidebar.html
@@ -1,8 +1,15 @@
 <h3>Download</h3>
 
 <p>Current version: <b>{{ version }}</b></p>
-<p>Get Setuptools from the <a href="https://pypi.python.org/pypi/setuptools"> Python Package Index</a>
+<p>Get Setuptools from the <a href="https://pypi.org/project/setuptools/"> Python Package Index</a>
 
 <h3>Questions? Suggestions? Contributions?</h3>
 
 <p>Visit the <a href="https://github.com/pypa/setuptools">Setuptools project page</a> </p>
+
+<h3 class="donation">Professional support</h3>
+
+<p>
+Professionally-supported {{ project }} is available with the
+<a href="https://tidelift.com/subscription/pkg/pypi-setuptools?utm_source=pypi-setuptools&utm_medium=readme">Tidelift Subscription</a>.
+</p>
diff --git a/docs/conf.py b/docs/conf.py
index f7d02303..c7eb6d3f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -34,7 +34,7 @@ import os
 
 # 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', 'sphinx.ext.autosectionlabel']
+extensions = ['jaraco.packaging.sphinx', 'rst.linker']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -45,6 +45,9 @@ 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.
+exclude_patterns = ['requirements.txt']
+
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
 exclude_trees = []
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
index 8a136380..a5942c8b 100644
--- a/docs/developer-guide.txt
+++ b/docs/developer-guide.txt
@@ -57,40 +57,59 @@ Setuptools makes extensive use of hyperlinks to tickets in the changelog so
 that system integrators and other users can get a quick summary, but then
 jump to the in-depth discussion about any subject referenced.
 
------------
-Source Code
------------
+---------------------
+Making a pull request
+---------------------
+
+When making a pull request, please include a short summary of the changes
+and a reference to any issue tickets that the PR is intended to solve.
+All PRs with code changes should include tests. All changes should include a
+changelog entry.
+
+``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
+for changelog management, so when making a PR, please add a news fragment in the
+``changelog.d/`` folder. Changelog files are written in reStructuredText and
+should be a 1 or 2 sentence description of the substantive changes in the PR.
+They should be named ``<pr_number>.<category>.rst``, where the categories are:
+
+- ``change``: Any backwards compatible code change
+- ``breaking``: Any backwards-compatibility breaking change
+- ``doc``: A change to the documentation
+- ``misc``: Changes internal to the repo like CI, test and build changes
+- ``deprecation``: For deprecations of an existing feature or behavior
+
+A pull request may have more than one of these components, for example a code
+change may introduce a new feature that deprecates an old feature, in which
+case two fragments should be added. It is not necessary to make a separate
+documentation fragment for documentation changes accompanying the relevant
+code changes. See the following for an example news fragment:
+
+.. code-block:: bash
+
+    $ cat changelog.d/1288.change.rst
+    Add support for maintainer in PKG-INFO
 
-Grab the code at Github::
-
-    $ git checkout https://github.com/pypa/setuptools
-
-If you want to contribute changes, we recommend you fork the repository on
-Github, commit the changes to your repository, and then make a pull request
-on Github. If you make some changes, don't forget to:
-
-- add a note in CHANGES.rst
-
-Please commit all changes in the 'master' branch against the latest available
-commit or for bug-fixes, against an earlier commit or release in which the
-bug occurred.
-
-If you find yourself working on more than one issue at a time, Setuptools
-generally prefers Git-style branches, so use Mercurial bookmarks or Git
-branches or multiple forks to maintain separate efforts.
+-------------------
+Auto-Merge Requests
+-------------------
 
-The Continuous Integration tests that validate every release are run
-from this repository.
+To support running all code through CI, even lightweight contributions,
+the project employs Mergify to auto-merge pull requests tagged as
+auto-merge.
 
-For posterity, the old `Bitbucket mirror
-<https://bitbucket.org/pypa/setuptools>`_ is available.
+Use ``hub pull-request -l auto-merge`` to create such a pull request
+from the command line after pushing a new branch.
 
 -------
 Testing
 -------
 
-The primary tests are run using tox. To run the tests, first make
-sure you have tox installed, then invoke it::
+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::
 
     $ tox
 
@@ -109,10 +128,12 @@ Setuptools follows ``semver``.
 Building Documentation
 ----------------------
 
-Setuptools relies on the Sphinx system for building documentation.
-To accommodate RTD, docs must be built from the docs/ directory.
+Setuptools relies on the `Sphinx`_ system for building documentation.
+The `published documentation`_ is hosted on Read the Docs.
+
+To build the docs locally, use tox::
 
-To build them, you need to have installed the requirements specified
-in docs/requirements.txt. One way to do this is to use rwt:
+    $ tox -e docs
 
-    setuptools/docs$ python -m rwt -r requirements.txt -- -m sphinx . html
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _published documentation: https://setuptools.readthedocs.io/en/latest/
diff --git a/docs/easy_install.txt b/docs/easy_install.txt
index bd9f0e86..aa11f890 100644
--- a/docs/easy_install.txt
+++ b/docs/easy_install.txt
@@ -2,6 +2,12 @@
 Easy Install
 ============
 
+.. warning::
+    Easy Install is deprecated. Do not use it. Instead use pip. If
+    you think you need Easy Install, please reach out to the PyPA
+    team (a ticket to pip or setuptools is fine), describing your
+    use-case.
+
 Easy Install is a python module (``easy_install``) bundled with ``setuptools``
 that lets you automatically download, build, install, and manage Python
 packages.
@@ -17,7 +23,7 @@ bug -- and then do so via list discussion first.)
 (Also, if you'd like to learn about how you can use ``setuptools`` to make your
 own packages work better with EasyInstall, or provide EasyInstall-like features
 without requiring your users to use EasyInstall directly, you'll probably want
-to check out the full `setuptools`_ documentation as well.)
+to check out the full documentation as well.)
 
 .. contents:: **Table of Contents**
 
@@ -31,11 +37,11 @@ Using "Easy Install"
 Installing "Easy Install"
 -------------------------
 
-Please see the `setuptools PyPI page <https://pypi.python.org/pypi/setuptools>`_
+Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_
 for download links and basic installation instructions for each of the
 supported platforms.
 
-You will need at least Python 2.6.  An ``easy_install`` script will be
+You will need at least Python 3.4 or 2.7.  An ``easy_install`` script will be
 installed in the normal location for Python scripts on your platform.
 
 Note that the instructions on the setuptools PyPI page assume that you are
@@ -305,8 +311,7 @@ Regardless of the technique used, the script(s) will be installed to a Scripts
 directory (by default in the Python installation directory). It is recommended
 for EasyInstall that you ensure this directory is in the PATH environment
 variable. The easiest way to ensure the Scripts directory is in the PATH is
-to run ``Tools\Scripts\win_add2path.py`` from the Python directory (requires
-Python 2.6 or later).
+to run ``Tools\Scripts\win_add2path.py`` from the Python directory.
 
 Note that instead of changing your ``PATH`` to include the Python scripts
 directory, you can also retarget the installation location for scripts so they
@@ -832,7 +837,7 @@ Command-Line Options
 
 ``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
     Specifies the base URL of the Python Package Index.  The default is
-    https://pypi.python.org/simple if not specified.  When a package is requested
+    https://pypi.org/simple/ if not specified.  When a package is requested
     that is not locally available or linked from a ``--find-links`` download
     page, the package index will be searched for download pages for the needed
     package, and those download pages will be searched for links to download
@@ -987,21 +992,20 @@ The following section lists only the easiest and most relevant approaches [1]_.
 
 `Use "virtualenv"`_
 
-.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_ in Python 2.6.
+.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_.
 
 .. _PEP-370: http://www.python.org/dev/peps/pep-0370/
 
 
 Use the "--user" option
 ~~~~~~~~~~~~~~~~~~~~~~~
-With Python 2.6 came the User scheme for installation, which means that all
-python distributions support an alternative install location that is specific to a user [2]_ [3]_.
+Python provides a User scheme for installation, which means that all
+python distributions support an alternative install location that is specific to a user [3]_.
 The Default location for each OS is explained in the python documentation
 for the ``site.USER_BASE`` variable.  This mode of installation can be turned on by
 specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
 This approach serves the need to have a user-specific stash of packages.
 
-.. [2] Prior to Python2.6, Mac OS X offered a form of the User scheme. That is now subsumed into the User scheme introduced in Python 2.6.
 .. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.
 
 Use the "--user" option and customize "PYTHONUSERBASE"
@@ -1021,7 +1025,7 @@ that the User installation scheme alone does not provide, e.g. the ability to hi
 
 Please refer to the `virtualenv`_ documentation for more details.
 
-.. _virtualenv: https://pypi.python.org/pypi/virtualenv
+.. _virtualenv: https://pypi.org/project/virtualenv/
 
 
 
@@ -1079,547 +1083,3 @@ EasyInstall to be able to look up and download packages:
 8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
    automatically use ``index.html`` files, if present, when trying to read a
    directory with a trailing ``/`` on the URL.
-
-
-Backward Compatibility
-~~~~~~~~~~~~~~~~~~~~~~
-
-Package indexes that wish to support setuptools versions prior to 0.6b4 should
-also follow these rules:
-
-* Homepage and download links must be preceded with ``"<th>Home Page"`` or
-  ``"<th>Download URL"``, in addition to (or instead of) the ``rel=""``
-  attributes on the actual links.  These marker strings do not need to be
-  visible, or uncommented, however!  For example, the following is a valid
-  homepage link that will work with any version of setuptools::
-
-    <li>
-     <strong>Home Page:</strong>
-     <!-- <th>Home Page -->
-     <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a>
-    </li>
-
-  Even though the marker string is in an HTML comment, older versions of
-  EasyInstall will still "see" it and know that the link that follows is the
-  project's home page URL.
-
-* The pages described by paragraph 3(b) of the preceding section *must*
-  contain the string ``"Index of Packages</title>"`` somewhere in their text.
-  This can be inside of an HTML comment, if desired, and it can be anywhere
-  in the page.  (Note: this string MUST NOT appear on normal project pages, as
-  described in paragraphs 2 and 3(a)!)
-
-In addition, for compatibility with PyPI versions that do not use ``#md5=``
-fragment IDs, EasyInstall uses the following regular expression to match PyPI's
-displayed MD5 info (broken onto two lines for readability)::
-
-    <a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5
-    &amp;digest=([0-9a-f]{32})">md5</a>\)
-
-History
-=======
-
-0.6c9
- * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting
-   is flattened out in the resulting egg.  (There was a case-sensitivity
-   problem that affected some distributions, notably ``pywin32``.)
-
- * Prevent ``--help-commands`` and other junk from showing under Python 2.5
-   when running ``easy_install --help``.
-
- * Fixed GUI scripts sometimes not executing on Windows
-
- * Fixed not picking up dependency links from recursive dependencies.
-
- * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs
-
- * Changes for Jython compatibility
-
- * Improved error message when a requirement is also a directory name, but the
-   specified directory is not a source package.
-
- * Fixed ``--allow-hosts`` option blocking ``file:`` URLs
-
- * Fixed HTTP SVN detection failing when the page title included a project
-   name (e.g. on SourceForge-hosted SVN)
-
- * Fix Jython script installation to handle ``#!`` lines better when
-   ``sys.executable`` is a script.
-
- * Removed use of deprecated ``md5`` module if ``hashlib`` is available
-
- * Keep site directories (e.g. ``site-packages``) from being included in
-   ``.pth`` files.
-
-0.6c7
- * ``ftp:`` download URLs now work correctly.
-
- * The default ``--index-url`` is now ``https://pypi.python.org/simple``, to use
-   the Python Package Index's new simpler (and faster!) REST API.
-
-0.6c6
- * EasyInstall no longer aborts the installation process if a URL it wants to
-   retrieve can't be downloaded, unless the URL is an actual package download.
-   Instead, it issues a warning and tries to keep going.
-
- * Fixed distutils-style scripts originally built on Windows having their line
-   endings doubled when installed on any platform.
-
- * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects
-   installed using ``setup.py develop``.
-
- * Fixed not HTML-decoding URLs scraped from web pages
-
-0.6c5
- * Fixed ``.dll`` files on Cygwin not having executable permissions when an egg
-   is installed unzipped.
-
-0.6c4
- * Added support for HTTP "Basic" authentication using ``http://user:pass@host``
-   URLs.  If a password-protected page contains links to the same host (and
-   protocol), those links will inherit the credentials used to access the
-   original page.
-
- * Removed all special support for Sourceforge mirrors, as Sourceforge's
-   mirror system now works well for non-browser downloads.
-
- * Fixed not recognizing ``win32.exe`` installers that included a custom
-   bitmap.
-
- * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they
-   are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as
-   is done by ``os.urandom()`` on some platforms).
-
- * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable``
-   has a space in it (e.g., the user installed Python to a ``Program Files``
-   directory).
-
-0.6c3
- * You can once again use "python -m easy_install" with Python 2.4 and above.
-
- * Python 2.5 compatibility fixes added.
-
-0.6c2
- * Windows script wrappers now support quoted arguments and arguments
-   containing spaces.  (Patch contributed by Jim Fulton.)
-
- * The ``ez_setup.py`` script now actually works when you put a setuptools
-   ``.egg`` alongside it for bootstrapping an offline machine.
-
- * A writable installation directory on ``sys.path`` is no longer required to
-   download and extract a source distribution using ``--editable``.
-
- * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable``
-   contains non-ASCII characters, to prevent deprecation warnings about an
-   unspecified encoding when the script is run.
-
-0.6c1
- * EasyInstall now includes setuptools version information in the
-   ``User-Agent`` string sent to websites it visits.
-
-0.6b4
- * Fix creating Python wrappers for non-Python scripts
-
- * Fix ``ftp://`` directory listing URLs from causing a crash when used in the
-   "Home page" or "Download URL" slots on PyPI.
-
- * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile
-   or directory is deleted/overwritten.
-
- * Fix not recognizing HTML 404 pages from package indexes.
-
- * Allow ``file://`` URLs to be used as a package index.  URLs that refer to
-   directories will use an internally-generated directory listing if there is
-   no ``index.html`` file in the directory.
-
- * Allow external links in a package index to be specified using
-   ``rel="homepage"`` or ``rel="download"``, without needing the old
-   PyPI-specific visible markup.
-
- * Suppressed warning message about possibly-misspelled project name, if an egg
-   or link for that project name has already been seen.
-
-0.6b3
- * Fix local ``--find-links`` eggs not being copied except with
-   ``--always-copy``.
-
- * Fix sometimes not detecting local packages installed outside of "site"
-   directories.
-
- * Fix mysterious errors during initial ``setuptools`` install, caused by
-   ``ez_setup`` trying to run ``easy_install`` twice, due to a code fallthru
-   after deleting the egg from which it's running.
-
-0.6b2
- * Don't install or update a ``site.py`` patch when installing to a
-   ``PYTHONPATH`` directory with ``--multi-version``, unless an
-   ``easy-install.pth`` file is already in use there.
-
- * Construct ``.pth`` file paths in such a way that installing an egg whose
-   name begins with ``import`` doesn't cause a syntax error.
-
- * Fixed a bogus warning message that wasn't updated since the 0.5 versions.
-
-0.6b1
- * Better ambiguity management: accept ``#egg`` name/version even if processing
-   what appears to be a correctly-named distutils file, and ignore ``.egg``
-   files with no ``-``, since valid Python ``.egg`` files always have a version
-   number (but Scheme eggs often don't).
-
- * Support ``file://`` links to directories in ``--find-links``, so that
-   easy_install can build packages from local source checkouts.
-
- * Added automatic retry for Sourceforge mirrors.  The new download process is
-   to first just try dl.sourceforge.net, then randomly select mirror IPs and
-   remove ones that fail, until something works.  The removed IPs stay removed
-   for the remainder of the run.
-
- * Ignore bdist_dumb distributions when looking at download URLs.
-
-0.6a11
- * Process ``dependency_links.txt`` if found in a distribution, by adding the
-   URLs to the list for scanning.
-
- * Use relative paths in ``.pth`` files when eggs are being installed to the
-   same directory as the ``.pth`` file.  This maximizes portability of the
-   target directory when building applications that contain eggs.
-
- * Added ``easy_install-N.N`` script(s) for convenience when using multiple
-   Python versions.
-
- * Added automatic handling of installation conflicts.  Eggs are now shifted to
-   the front of sys.path, in an order consistent with where they came from,
-   making EasyInstall seamlessly co-operate with system package managers.
-
-   The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options
-   are now no longer necessary, and will generate warnings at the end of a
-   run if you use them.
-
- * Don't recursively traverse subdirectories given to ``--find-links``.
-
-0.6a10
- * Added exhaustive testing of the install directory, including a spawn test
-   for ``.pth`` file support, and directory writability/existence checks.  This
-   should virtually eliminate the need to set or configure ``--site-dirs``.
-
- * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of
-   RTFM-ing.  :)
-
- * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it
-   manually to make it work.  ``--multi-version`` is no longer a silent
-   default; you must explicitly use it if installing to a non-PYTHONPATH,
-   non-"site" directory.
-
- * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``,
-   ``--install-dir``, and ``--script-dir`` options, whether on the command line
-   or in configuration files.
-
- * Improved SourceForge mirror processing to work faster and be less affected
-   by transient HTML changes made by SourceForge.
-
- * PyPI searches now use the exact spelling of requirements specified on the
-   command line or in a project's ``install_requires``.  Previously, a
-   normalized form of the name was used, which could lead to unnecessary
-   full-index searches when a project's name had an underscore (``_``) in it.
-
- * EasyInstall can now download bare ``.py`` files and wrap them in an egg,
-   as long as you include an ``#egg=name-version`` suffix on the URL, or if
-   the ``.py`` file is listed as the "Download URL" on the project's PyPI page.
-   This allows third parties to "package" trivial Python modules just by
-   linking to them (e.g. from within their own PyPI page or download links
-   page).
-
- * The ``--always-copy`` option now skips "system" and "development" eggs since
-   they can't be reliably copied.  Note that this may cause EasyInstall to
-   choose an older version of a package than what you expected, or it may cause
-   downloading and installation of a fresh version of what's already installed.
-
- * The ``--find-links`` option previously scanned all supplied URLs and
-   directories as early as possible, but now only directories and direct
-   archive links are scanned immediately.  URLs are not retrieved unless a
-   package search was already going to go online due to a package not being
-   available locally, or due to the use of the ``--update`` or ``-U`` option.
-
- * Fixed the annoying ``--help-commands`` wart.
-
-0.6a9
- * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside
-   "baskets") when they weren't explicitly listed in the ``.pth`` file.
-
- * If more than one URL appears to describe the exact same distribution, prefer
-   the shortest one.  This helps to avoid "table of contents" CGI URLs like the
-   ones on effbot.org.
-
- * Quote arguments to python.exe (including python's path) to avoid problems
-   when Python (or a script) is installed in a directory whose name contains
-   spaces on Windows.
-
- * Support full roundtrip translation of eggs to and from ``bdist_wininst``
-   format.  Running ``bdist_wininst`` on a setuptools-based package wraps the
-   egg in an .exe that will safely install it as an egg (i.e., with metadata
-   and entry-point wrapper scripts), and ``easy_install`` can turn the .exe
-   back into an ``.egg`` file or directory and install it as such.
-
-0.6a8
- * Update for changed SourceForge mirror format
-
- * Fixed not installing dependencies for some packages fetched via Subversion
-
- * Fixed dependency installation with ``--always-copy`` not using the same
-   dependency resolution procedure as other operations.
-
- * Fixed not fully removing temporary directories on Windows, if a Subversion
-   checkout left read-only files behind
-
- * Fixed some problems building extensions when Pyrex was installed, especially
-   with Python 2.4 and/or packages using SWIG.
-
-0.6a7
- * Fixed not being able to install Windows script wrappers using Python 2.3
-
-0.6a6
- * Added support for "traditional" PYTHONPATH-based non-root installation, and
-   also the convenient ``virtual-python.py`` script, based on a contribution
-   by Ian Bicking.  The setuptools egg now contains a hacked ``site`` module
-   that makes the PYTHONPATH-based approach work with .pth files, so that you
-   can get the full EasyInstall feature set on such installations.
-
- * Added ``--no-deps`` and ``--allow-hosts`` options.
-
- * Improved Windows ``.exe`` script wrappers so that the script can have the
-   same name as a module without confusing Python.
-
- * Changed dependency processing so that it's breadth-first, allowing a
-   depender's preferences to override those of a dependee, to prevent conflicts
-   when a lower version is acceptable to the dependee, but not the depender.
-   Also, ensure that currently installed/selected packages aren't given
-   precedence over ones desired by a package being installed, which could
-   cause conflict errors.
-
-0.6a3
- * Improved error message when trying to use old ways of running
-   ``easy_install``.  Removed the ability to run via ``python -m`` or by
-   running ``easy_install.py``; ``easy_install`` is the command to run on all
-   supported platforms.
-
- * Improved wrapper script generation and runtime initialization so that a
-   VersionConflict doesn't occur if you later install a competing version of a
-   needed package as the default version of that package.
-
- * Fixed a problem parsing version numbers in ``#egg=`` links.
-
-0.6a2
- * EasyInstall can now install "console_scripts" defined by packages that use
-   ``setuptools`` and define appropriate entry points.  On Windows, console
-   scripts get an ``.exe`` wrapper so you can just type their name.  On other
-   platforms, the scripts are installed without a file extension.
-
- * Using ``python -m easy_install`` or running ``easy_install.py`` is now
-   DEPRECATED, since an ``easy_install`` wrapper is now available on all
-   platforms.
-
-0.6a1
- * EasyInstall now does MD5 validation of downloads from PyPI, or from any link
-   that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest.
-
- * EasyInstall now handles symlinks in target directories by removing the link,
-   rather than attempting to overwrite the link's destination.  This makes it
-   easier to set up an alternate Python "home" directory (as described above in
-   the `Non-Root Installation`_ section).
-
- * Added support for handling MacOS platform information in ``.egg`` filenames,
-   based on a contribution by Kevin Dangoor.  You may wish to delete and
-   reinstall any eggs whose filename includes "darwin" and "Power_Macintosh",
-   because the format for this platform information has changed so that minor
-   OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
-   previous OS version to become obsolete.
-
- * easy_install's dependency processing algorithms have changed.  When using
-   ``--always-copy``, it now ensures that dependencies are copied too.  When
-   not using ``--always-copy``, it tries to use a single resolution loop,
-   rather than recursing.
-
- * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
-   extensions.
-
- * Added ``--site-dirs`` option to allow adding custom "site" directories.
-   Made ``easy-install.pth`` work in platform-specific alternate site
-   directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X).
-
- * If you manually delete the current version of a package, the next run of
-   EasyInstall against the target directory will now remove the stray entry
-   from the ``easy-install.pth`` file.
-
- * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID
-   as pointing to the named project's source checkout.  Such URLs have a lower
-   match precedence than any other kind of distribution, so they'll only be
-   used if they have a higher version number than any other available
-   distribution, or if you use the ``--editable`` option.  The ``#egg``
-   fragment can contain a version if it's formatted as ``#egg=proj-ver``,
-   where ``proj`` is the project name, and ``ver`` is the version number.  You
-   *must* use the format for these values that the ``bdist_egg`` command uses;
-   i.e., all non-alphanumeric runs must be condensed to single underscore
-   characters.
-
- * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_
-   above for more info.  Also, slightly changed the behavior of the
-   ``--build-directory`` option.
-
- * Fixed the setup script sandbox facility not recognizing certain paths as
-   valid on case-insensitive platforms.
-
-0.5a12
- * Fix ``python -m easy_install`` not working due to setuptools being installed
-   as a zipfile.  Update safety scanner to check for modules that might be used
-   as ``python -m`` scripts.
-
- * Misc. fixes for win32.exe support, including changes to support Python 2.4's
-   changed ``bdist_wininst`` format.
-
-0.5a10
- * Put the ``easy_install`` module back in as a module, as it's needed for
-   ``python -m`` to run it!
-
- * Allow ``--find-links/-f`` to accept local directories or filenames as well
-   as URLs.
-
-0.5a9
- * EasyInstall now automatically detects when an "unmanaged" package or
-   module is going to be on ``sys.path`` ahead of a package you're installing,
-   thereby preventing the newer version from being imported.  By default, it
-   will abort installation to alert you of the problem, but there are also
-   new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``)
-   available to change the default behavior.  (Note: this new feature doesn't
-   take effect for egg files that were built with older ``setuptools``
-   versions, because they lack the new metadata file required to implement it.)
-
- * The ``easy_install`` distutils command now uses ``DistutilsError`` as its
-   base error type for errors that should just issue a message to stderr and
-   exit the program without a traceback.
-
- * EasyInstall can now be given a path to a directory containing a setup
-   script, and it will attempt to build and install the package there.
-
- * EasyInstall now performs a safety analysis on module contents to determine
-   whether a package is likely to run in zipped form, and displays
-   information about what modules may be doing introspection that would break
-   when running as a zipfile.
-
- * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that
-   would ordinarily be considered safe to unzip, and changed the meaning of
-   ``--zip-ok/-z`` to "always leave everything zipped".
-
-0.5a8
- * There is now a separate documentation page for `setuptools`_; revision
-   history that's not specific to EasyInstall has been moved to that page.
-
- .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
-
-0.5a5
- * Made ``easy_install`` a standard ``setuptools`` command, moving it from
-   the ``easy_install`` module to ``setuptools.command.easy_install``.  Note
-   that if you were importing or extending it, you must now change your imports
-   accordingly.  ``easy_install.py`` is still installed as a script, but not as
-   a module.
-
-0.5a4
- * Added ``--always-copy/-a`` option to always copy needed packages to the
-   installation directory, even if they're already present elsewhere on
-   sys.path. (In previous versions, this was the default behavior, but now
-   you must request it.)
-
- * Added ``--upgrade/-U`` option to force checking PyPI for latest available
-   version(s) of all packages requested by name and version, even if a matching
-   version is available locally.
-
- * Added automatic installation of dependencies declared by a distribution
-   being installed.  These dependencies must be listed in the distribution's
-   ``EGG-INFO`` directory, so the distribution has to have declared its
-   dependencies by using setuptools.  If a package has requirements it didn't
-   declare, you'll still have to deal with them yourself.  (E.g., by asking
-   EasyInstall to find and install them.)
-
- * Added the ``--record`` option to ``easy_install`` for the benefit of tools
-   that run ``setup.py install --record=filename`` on behalf of another
-   packaging system.)
-
-0.5a3
- * Fixed not setting script permissions to allow execution.
-
- * Improved sandboxing so that setup scripts that want a temporary directory
-   (e.g. pychecker) can still run in the sandbox.
-
-0.5a2
- * Fix stupid stupid refactoring-at-the-last-minute typos.  :(
-
-0.5a1
- * Added support for converting ``.win32.exe`` installers to eggs on the fly.
-   EasyInstall will now recognize such files by name and install them.
-
- * Fixed a problem with picking the "best" version to install (versions were
-   being sorted as strings, rather than as parsed values)
-
-0.4a4
- * Added support for the distutils "verbose/quiet" and "dry-run" options, as
-   well as the "optimize" flag.
-
- * Support downloading packages that were uploaded to PyPI (by scanning all
-   links on package pages, not just the homepage/download links).
-
-0.4a3
- * Add progress messages to the search/download process so that you can tell
-   what URLs it's reading to find download links.  (Hopefully, this will help
-   people report out-of-date and broken links to package authors, and to tell
-   when they've asked for a package that doesn't exist.)
-
-0.4a2
- * Added support for installing scripts
-
- * Added support for setting options via distutils configuration files, and
-   using distutils' default options as a basis for EasyInstall's defaults.
-
- * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the
-   script installation directory option.
-
- * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
-   Python includes SSL support.
-
-0.4a1
- * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
-   and search PyPI for needed packages.
-
-0.3a4
- * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
-   URL installs, to avoid running the wrong setup.py.
-
-0.3a3
- * Added ``--build-directory=DIR/-b DIR`` option.
-
- * Added "installation report" that explains how to use 'require()' when doing
-   a multiversion install or alternate installation directory.
-
- * Added SourceForge mirror auto-select (Contributed by Ian Bicking)
-
- * Added "sandboxing" that stops a setup script from running if it attempts to
-   write to the filesystem outside of the build area
-
- * Added more workarounds for packages with quirky ``install_data`` hacks
-
-0.3a2
- * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
-   automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)
-
- * Misc. bug fixes
-
-0.3a1
- * Initial release.
-
-
-Future Plans
-============
-
-* Additional utilities to list/remove/verify packages
-* Signature checking?  SSL?  Ability to suppress PyPI search?
-* Display byte progress meter when downloading distributions and long pages?
-* Redirect stdout/stderr to log during run_setup?
-
diff --git a/docs/ez_setup.txt b/docs/ez_setup.txt
new file mode 100644
index 00000000..0126fee3
--- /dev/null
+++ b/docs/ez_setup.txt
@@ -0,0 +1,195 @@
+:orphan:
+
+``ez_setup`` distribution guide 
+===============================
+
+Using ``setuptools``...  Without bundling it!
+---------------------------------------------
+
+.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support.
+
+.. _ez_setup.py: https://bootstrap.pypa.io/ez_setup.py
+
+.. _EasyInstall Installation Instructions: easy_install.html
+
+.. _Custom Installation Locations: easy_install.html
+
+Your users might not have ``setuptools`` installed on their machines, or even
+if they do, it might not be the right version.  Fixing this is easy; just
+download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
+script.  (Be sure to add it to your revision control system, too.)  Then add
+these two lines to the very top of your setup script, before the script imports
+anything from setuptools:
+
+.. code-block:: python
+
+    import ez_setup
+    ez_setup.use_setuptools()
+
+That's it.  The ``ez_setup`` module will automatically download a matching
+version of ``setuptools`` from PyPI, if it isn't present on the target system.
+Whenever you install an updated version of setuptools, you should also update
+your projects' ``ez_setup.py`` files, so that a matching version gets installed
+on the target machine(s).
+
+(By the way, if you need to distribute a specific version of ``setuptools``,
+you can specify the exact version and base download URL as parameters to the
+``use_setuptools()`` function.  See the function's docstring for details.)
+
+
+What Your Users Should Know
+---------------------------
+
+In general, a setuptools-based project looks just like any distutils-based
+project -- as long as your users have an internet connection and are installing
+to ``site-packages``, that is.  But for some users, these conditions don't
+apply, and they may become frustrated if this is their first encounter with
+a setuptools-based project.  To keep these users happy, you should review the
+following topics in your project's installation instructions, if they are
+relevant to your project and your target audience isn't already familiar with
+setuptools and ``easy_install``.
+
+Network Access
+    If your project is using ``ez_setup``, you should inform users of the
+    need to either have network access, or to preinstall the correct version of
+    setuptools using the `EasyInstall installation instructions`_.  Those
+    instructions also have tips for dealing with firewalls as well as how to
+    manually download and install setuptools.
+
+Custom Installation Locations
+    You should inform your users that if they are installing your project to
+    somewhere other than the main ``site-packages`` directory, they should
+    first install setuptools using the instructions for `Custom Installation
+    Locations`_, before installing your project.
+
+Your Project's Dependencies
+    If your project depends on other projects that may need to be downloaded
+    from PyPI or elsewhere, you should list them in your installation
+    instructions, or tell users how to find out what they are.  While most
+    users will not need this information, any users who don't have unrestricted
+    internet access may have to find, download, and install the other projects
+    manually.  (Note, however, that they must still install those projects
+    using ``easy_install``, or your project will not know they are installed,
+    and your setup script will try to download them again.)
+
+    If you want to be especially friendly to users with limited network access,
+    you may wish to build eggs for your project and its dependencies, making
+    them all available for download from your site, or at least create a page
+    with links to all of the needed eggs.  In this way, users with limited
+    network access can manually download all the eggs to a single directory,
+    then use the ``-f`` option of ``easy_install`` to specify the directory
+    to find eggs in.  Users who have full network access can just use ``-f``
+    with the URL of your download page, and ``easy_install`` will find all the
+    needed eggs using your links directly.  This is also useful when your
+    target audience isn't able to compile packages (e.g. most Windows users)
+    and your package or some of its dependencies include C code.
+
+Revision Control System Users and Co-Developers
+    Users and co-developers who are tracking your in-development code using
+    a revision control system should probably read this manual's sections
+    regarding such development.  Alternately, you may wish to create a
+    quick-reference guide containing the tips from this manual that apply to
+    your particular situation.  For example, if you recommend that people use
+    ``setup.py develop`` when tracking your in-development code, you should let
+    them know that this needs to be run after every update or commit.
+
+    Similarly, if you remove modules or data files from your project, you
+    should remind them to run ``setup.py clean --all`` and delete any obsolete
+    ``.pyc`` or ``.pyo``.  (This tip applies to the distutils in general, not
+    just setuptools, but not everybody knows about them; be kind to your users
+    by spelling out your project's best practices rather than leaving them
+    guessing.)
+
+Creating System Packages
+    Some users want to manage all Python packages using a single package
+    manager, and sometimes that package manager isn't ``easy_install``!
+    Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
+    ``bdist_dumb`` formats for system packaging.  If a user has a locally-
+    installed "bdist" packaging tool that internally uses the distutils
+    ``install`` command, it should be able to work with ``setuptools``.  Some
+    examples of "bdist" formats that this should work with include the
+    ``bdist_nsi`` and ``bdist_msi`` formats for Windows.
+
+    However, packaging tools that build binary distributions by running
+    ``setup.py install`` on the command line or as a subprocess will require
+    modification to work with setuptools.  They should use the
+    ``--single-version-externally-managed`` option to the ``install`` command,
+    combined with the standard ``--root`` or ``--record`` options.
+    See the `install command`_ documentation below for more details.  The
+    ``bdist_deb`` command is an example of a command that currently requires
+    this kind of patching to work with setuptools.
+
+    Please note that building system packages may require you to install
+    some system software, for example ``bdist_rpm`` requires the ``rpmbuild``
+    command to be installed.
+
+    If you or your users have a problem building a usable system package for
+    your project, please report the problem via the mailing list so that
+    either the "bdist" tool in question or setuptools can be modified to
+    resolve the issue.
+
+Your users might not have ``setuptools`` installed on their machines, or even
+if they do, it might not be the right version.  Fixing this is easy; just
+download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
+script.  (Be sure to add it to your revision control system, too.)  Then add
+these two lines to the very top of your setup script, before the script imports
+anything from setuptools:
+
+.. code-block:: python
+
+    import ez_setup
+    ez_setup.use_setuptools()
+
+That's it.  The ``ez_setup`` module will automatically download a matching
+version of ``setuptools`` from PyPI, if it isn't present on the target system.
+Whenever you install an updated version of setuptools, you should also update
+your projects' ``ez_setup.py`` files, so that a matching version gets installed
+on the target machine(s).
+
+(By the way, if you need to distribute a specific version of ``setuptools``,
+you can specify the exact version and base download URL as parameters to the
+``use_setuptools()`` function.  See the function's docstring for details.)
+
+.. _install command:
+
+``install`` - Run ``easy_install`` or old-style installation
+============================================================
+
+The setuptools ``install`` command is basically a shortcut to run the
+``easy_install`` command on the current project.  However, for convenience
+in creating "system packages" of setuptools-based projects, you can also
+use this option:
+
+``--single-version-externally-managed``
+    This boolean option tells the ``install`` command to perform an "old style"
+    installation, with the addition of an ``.egg-info`` directory so that the
+    installed project will still have its metadata available and operate
+    normally.  If you use this option, you *must* also specify the ``--root``
+    or ``--record`` options (or both), because otherwise you will have no way
+    to identify and remove the installed files.
+
+This option is automatically in effect when ``install`` is invoked by another
+distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
+will create system packages of eggs.  It is also automatically in effect if
+you specify the ``--root`` option.
+
+
+``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
+==============================================================================
+
+Setuptools runs this command as part of ``install`` operations that use the
+``--single-version-externally-managed`` options.  You should not invoke it
+directly; it is documented here for completeness and so that distutils
+extensions such as system package builders can make use of it.  This command
+has only one option:
+
+``--install-dir=DIR, -d DIR``
+    The parent directory where the ``.egg-info`` directory will be placed.
+    Defaults to the same as the ``--install-dir`` option specified for the
+    ``install_lib`` command, which is usually the system ``site-packages``
+    directory.
+
+This command assumes that the ``egg_info`` command has been given valid options
+via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
+command and use its options to locate the project's source ``.egg-info``
+directory.
diff --git a/docs/formats.txt b/docs/formats.txt
index 9e6fe727..a182eb99 100644
--- a/docs/formats.txt
+++ b/docs/formats.txt
@@ -110,7 +110,7 @@ the need to create a directory just to store one file.  This option is
 other metadata.  (In fact, setuptools itself never generates
 ``.egg-info`` files, either; the support for using files was added so
 that the requirement could easily be satisfied by other tools, such
-as the distutils in Python 2.5).
+as distutils).
 
 In addition to the ``PKG-INFO`` file, an egg's metadata directory may
 also include files and directories representing various forms of
diff --git a/docs/history.txt b/docs/history.txt
index 8fd1dc65..385cfa7e 100644
--- a/docs/history.txt
+++ b/docs/history.txt
@@ -40,7 +40,6 @@ Credits
   re-invigorated the community on the project, encouraged renewed innovation,
   and addressed many defects.
 
-* Since the merge with Distribute, Jason R. Coombs is the
-  maintainer of setuptools. The project is maintained in coordination with
-  the Python Packaging Authority (PyPA) and the larger Python community.
-
+* Jason R. Coombs performed the merge with Distribute, maintaining the
+  project for several years in coordination with the Python Packaging
+  Authority (PyPA).
diff --git a/docs/index.txt b/docs/index.txt
index 74aabb5e..13a46e74 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -17,9 +17,9 @@ Documentation content:
    :maxdepth: 2
 
    setuptools
-   easy_install
    pkg_resources
    python3
    development
    roadmap
+   Deprecated: Easy Install <easy_install>
    history
diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt
index 487320ce..0c9fb5f2 100644
--- a/docs/pkg_resources.txt
+++ b/docs/pkg_resources.txt
@@ -620,8 +620,8 @@ Requirements Parsing
     The "markers" in a requirement are used to specify when a requirement
     should be installed -- the requirement will be installed if the marker
     evaluates as true in the current environment. For example, specifying
-    ``argparse;python_version<"2.7"`` will not install in an Python 2.7 or 3.3
-    environment, but will in a Python 2.6 environment.
+    ``argparse;python_version<"3.0"`` will not install in an Python 3
+    environment, but will in a Python 2 environment.
 
 ``Requirement`` Methods and Attributes
 --------------------------------------
@@ -638,7 +638,7 @@ Requirements Parsing
     sorted into ascending version order, and used to establish what ranges of
     versions are acceptable.  Adjacent redundant conditions are effectively
     consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and
-    ``"<2,<3"`` produces the same results as``"<2"``). ``"!="`` versions are
+    ``"<2,<3"`` produces the same results as ``"<2"``). ``"!="`` versions are
     excised from the ranges they fall within.  The version being tested for
     acceptability is then checked for membership in the resulting ranges.
 
@@ -703,7 +703,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.  (XXX link here to setuptools)
+details, see the [``setuptools`` documentation](https://setuptools.readthedocs.io/en/latest/setuptools.html#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
@@ -1087,6 +1087,7 @@ so that supporting custom importers or new distribution formats can be done
 simply by creating an appropriate `IResourceProvider`_ implementation; see the
 section below on `Supporting Custom Importers`_ for more details.
 
+.. _ResourceManager API:
 
 ``ResourceManager`` API
 =======================
@@ -1658,19 +1659,7 @@ PEP 302 Utilities
 -----------------
 
 ``get_importer(path_item)``
-    Retrieve a PEP 302 "importer" for the given path item (which need not
-    actually be on ``sys.path``).  This routine simulates the PEP 302 protocol
-    for obtaining an "importer" object.  It first checks for an importer for
-    the path item in ``sys.path_importer_cache``, and if not found it calls
-    each of the ``sys.path_hooks`` and caches the result if a good importer is
-    found.  If no importer is found, this routine returns an ``ImpWrapper``
-    instance that wraps the builtin import machinery as a PEP 302-compliant
-    "importer" object.  This ``ImpWrapper`` is *not* cached; instead a new
-    instance is returned each time.
-
-    (Note: When run under Python 2.5, this function is simply an alias for
-    ``pkgutil.get_importer()``, and instead of ``pkg_resources.ImpWrapper``
-    instances, it may return ``pkgutil.ImpImporter`` instances.)
+    A deprecated alias for ``pkgutil.get_importer()``
 
 
 File/Path Utilities
diff --git a/docs/python3.txt b/docs/python3.txt
index d550cb68..6b55fe78 100644
--- a/docs/python3.txt
+++ b/docs/python3.txt
@@ -9,9 +9,9 @@ code.
 
 Setuptools provides a facility to invoke 2to3 on the code as a part of the
 build process, by setting the keyword parameter ``use_2to3`` to True, but
-the Setuptools strongly recommends instead developing a unified codebase
-using `six <https://pypi.python.org/pypi/six>`_,
-`future <https://pypi.python.org/pypi/future>`_, or another compatibility
+the Setuptools project strongly recommends instead developing a unified codebase
+using `six <https://pypi.org/project/six/>`_,
+`future <https://pypi.org/project/future/>`_, or another compatibility
 library.
 
 
diff --git a/docs/releases.txt b/docs/releases.txt
index 30ea084f..98ba39e8 100644
--- a/docs/releases.txt
+++ b/docs/releases.txt
@@ -7,20 +7,35 @@ 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 check that the CHANGES.rst reflects
-the summary of changes since the last release.
-Ideally, these changelog entries would have been added
-along with the changes, but it's always good to check.
-Think about it from the
-perspective of a user not involved with the development--what would
-that person want to know about what has changed--or from the
-perspective of your future self wanting to know when a particular
-change landed.
-
-To cut a release, install and run ``bump2version {part}`` where ``part``
+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. If tests pass,
-the release will be uploaded to PyPI (from the Python 3.6 tests).
+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/
 
 Release Frequency
 -----------------
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2138c884..c6d594e8 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,4 @@
-sphinx
+sphinx!=1.8.0
 rst.linker>=1.9
 jaraco.packaging>=3.2
 
diff --git a/docs/roadmap.txt b/docs/roadmap.txt
index 8f175b9f..147288f3 100644
--- a/docs/roadmap.txt
+++ b/docs/roadmap.txt
@@ -2,5 +2,6 @@
 Roadmap
 =======
 
-Setuptools is primarily in maintenance mode. The project attempts to address
-user issues, concerns, and feature requests in a timely fashion.
+Setuptools maintains a series of `milestones
+<https://github.com/pypa/setuptools/milestones>`_ to track
+a roadmap of large-scale goals.
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index f255cfd2..cf166e9c 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -3,7 +3,7 @@ Building and Distributing Packages with Setuptools
 ==================================================
 
 ``Setuptools`` is a collection of enhancements to the Python ``distutils``
-(for Python 2.6 and up) that allow developers to more easily build and
+that allow developers to more easily build and
 distribute Python packages, especially ones that have dependencies on other
 packages.
 
@@ -41,15 +41,13 @@ Feature Highlights:
   files for any number of "main" functions in your project.  (Note: this is not
   a py2exe replacement; the .exe files rely on the local Python installation.)
 
-* Transparent Pyrex support, so that your setup.py can list ``.pyx`` files and
-  still work even when the end-user doesn't have Pyrex installed (as long as
-  you include the Pyrex-generated C in your source distribution)
+* Transparent Cython support, so that your setup.py can list ``.pyx`` files and
+  still work even when the end-user doesn't have Cython installed (as long as
+  you include the Cython-generated C in your source distribution)
 
 * Command aliases - create project-specific, per-user, or site-wide shortcut
   names for commonly used commands and options
 
-* PyPI upload support - upload your source distributions and eggs to PyPI
-
 * Deploy your project in "development mode", such that it's available on
   ``sys.path``, yet can still be edited directly from its source checkout.
 
@@ -59,6 +57,9 @@ Feature Highlights:
 * Create extensible applications and frameworks that automatically discover
   extensions, using simple "entry points" declared in a project's setup script.
 
+* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
+  compatible to the existing ``find_packages()`` for Python >= 3.3.
+
 .. contents:: **Table of Contents**
 
 .. _ez_setup.py: `bootstrap module`_
@@ -72,23 +73,17 @@ Developer's Guide
 Installing ``setuptools``
 =========================
 
-Please follow the `EasyInstall Installation Instructions`_ to install the
-current stable version of setuptools.  In particular, be sure to read the
-section on `Custom Installation Locations`_ if you are installing anywhere
-other than Python's ``site-packages`` directory.
-
-.. _EasyInstall Installation Instructions: easy_install.html#installation-instructions
+.. _EasyInstall Installation Instructions: easy_install.html
 
-.. _Custom Installation Locations: easy_install.html#custom-installation-locations
+.. _Custom Installation Locations: easy_install.html
 
-If you want the current in-development version of setuptools, you should first
-install a stable version, and then run::
+.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
 
-    ez_setup.py setuptools==dev
+To install the latest version of setuptools, use::
 
-This will download and install the latest development (i.e. unstable) version
-of setuptools from the Python Subversion sandbox.
+    pip install -U setuptools
 
+Refer to `Installing Packages`_ guide for more information.
 
 Basic Use
 =========
@@ -107,11 +102,10 @@ As you can see, it doesn't take much to use setuptools in a project.
 Run that script in your project folder, alongside the Python packages
 you have developed.
 
-Invoke that script to produce eggs, upload to
-PyPI, and automatically include all 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::
+Invoke that script to produce distributions and automatically include all
+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
 
@@ -138,13 +132,18 @@ dependencies, and perhaps some data files and scripts::
             'hello': ['*.msg'],
         },
 
-        # metadata for upload to PyPI
+        # metadata to display on PyPI
         author="Me",
         author_email="me@example.com",
         description="This is an Example Package",
         license="PSF",
         keywords="hello world example examples",
         url="http://example.com/HelloWorld/",   # project home page, if any
+        project_urls={
+            "Bug Tracker": "https://bugs.example.com/HelloWorld/",
+            "Documentation": "https://docs.example.com/HelloWorld/",
+            "Source Code": "https://code.example.com/HelloWorld/",
+        }
 
         # could also include long_description, download_url, classifiers, etc.
     )
@@ -237,7 +236,6 @@ have setuptools automatically tag your in-development releases with various
 pre- or post-release tags.  See the following sections for more details:
 
 * `Tagging and "Daily Build" or "Snapshot" Releases`_
-* `Managing "Continuous Releases" Using Subversion`_
 * The `egg_info`_ command
 
 
@@ -408,6 +406,11 @@ unless you need the associated ``setuptools`` feature.
     A list of modules to search for additional fixers to be used during
     the 2to3 conversion. See :doc:`python3` for more details.
 
+``project_urls``
+    An arbitrary map of URL names to hyperlinks, allowing more extensible
+    documentation of where various resources can be found than the simple
+    ``url`` and ``download_url`` options provide.
+
 
 Using ``find_packages()``
 -------------------------
@@ -427,9 +430,9 @@ 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
-patterns, and finds Python packages (any directory). On Python 3.2 and
-earlier, packages are only recognized if they include an ``__init__.py`` file.
-Finally, exclusion patterns are applied to remove matching packages.
+patterns, and finds Python packages (any directory). Packages are only
+recognized if they include an ``__init__.py`` file. Finally, exclusion
+patterns are applied to remove matching packages.
 
 Inclusion and exclusion patterns are package names, optionally including
 wildcards.  For
@@ -453,6 +456,67 @@ argument in your setup script.  Especially since it frees you from having to
 remember to modify your setup script whenever your project grows additional
 top-level packages or subpackages.
 
+``find_namespace_packages()``
+-----------------------------
+In Python 3.3+, ``setuptools`` also provides the ``find_namespace_packages`` variant
+of ``find_packages``, which has the same function signature as
+``find_packages``, but works with `PEP 420`_ compliant implicit namespace
+packages. Here is a minimal setup script using ``find_namespace_packages``::
+
+    from setuptools import setup, find_namespace_packages
+    setup(
+        name="HelloWorld",
+        version="0.1",
+        packages=find_namespace_packages(),
+    )
+
+
+Keep in mind that according to PEP 420, you may have to either re-organize your
+codebase a bit or define a few exclusions, as the definition of an implicit
+namespace package is quite lenient, so for a project organized like so::
+
+
+    ├── namespace
+    │   └── mypackage
+    │       ├── __init__.py
+    │       └── mod1.py
+    ├── setup.py
+    └── tests
+        └── test_mod1.py
+
+A naive ``find_namespace_packages()`` would install both ``namespace.mypackage`` and a
+top-level package called ``tests``! One way to avoid this problem is to use the
+``include`` keyword to whitelist the packages to include, like so::
+
+    from setuptools import setup, find_namespace_packages
+
+    setup(
+        name="namespace.mypackage",
+        version="0.1",
+        packages=find_namespace_packages(include=['namespace.*'])
+    )
+
+Another option is to use the "src" layout, where all package code is placed in
+the ``src`` directory, like so::
+
+
+    ├── setup.py
+    ├── src
+    │   └── namespace
+    │       └── mypackage
+    │           ├── __init__.py
+    │           └── mod1.py
+    └── tests
+        └── test_mod1.py
+
+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'))
+
+.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
 
 Automatic Script Creation
 =========================
@@ -561,7 +625,7 @@ project name or version identifier must be replaced with ``-``.
 Version specifiers for a given project are internally sorted into ascending
 version order, and used to establish what ranges of versions are acceptable.
 Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
-``">1"``, and ``"<2,<3"`` becomes ``"<3"``). ``"!="`` versions are excised from
+``">2"``, and ``"<2,<3"`` becomes ``"<2"``). ``"!="`` versions are excised from
 the ranges they fall within.  A project's version is then checked for
 membership in the resulting ranges. (Note that providing conflicting conditions
 for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
@@ -609,9 +673,8 @@ using ``setup.py develop``.)
 Dependencies that aren't in PyPI
 --------------------------------
 
-If your project depends on packages that aren't registered in PyPI, you may
-still be able to depend on them, as long as they are available for download
-as:
+If your project depends on packages that don't exist on PyPI, you may still be
+able to depend on them, as long as they are available for download as:
 
 - an egg, in the standard distutils ``sdist`` format,
 - a single ``.py`` file, or
@@ -875,6 +938,14 @@ Also notice that if you use paths, you *must* use a forward slash (``/``) as
 the path separator, even if you are on Windows.  Setuptools automatically
 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'``).
+
+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
+the ``setup.py`` ``package_data`` list is updated before calling ``setup.py``.
+
 (Note: although the ``package_data`` argument was previously only available in
 ``setuptools``, it was also added to the Python ``distutils`` package as of
 Python 2.4; there is `some documentation for the feature`__ available on the
@@ -916,7 +987,7 @@ In summary, the three options allow you to:
     Accept all data files and directories matched by ``MANIFEST.in``.
 
 ``package_data``
-    Specify additional patterns to match files and directories that may or may
+    Specify additional patterns to match files that may or may
     not be matched by ``MANIFEST.in`` or found in source control.
 
 ``exclude_package_data``
@@ -953,35 +1024,14 @@ a quick example of converting code that uses ``__file__`` to use
 Non-Package Data Files
 ----------------------
 
-The ``distutils`` normally install general "data files" to a platform-specific
-location (e.g. ``/usr/share``).  This feature intended to be used for things
-like documentation, example configuration files, and the like.  ``setuptools``
-does not install these data files in a separate location, however.  They are
-bundled inside the egg file or directory, alongside the Python modules and
-packages.  The data files can also be accessed using the :ref:`ResourceManager
-API`, by specifying a ``Requirement`` instead of a package name::
-
-    from pkg_resources import Requirement, resource_filename
-    filename = resource_filename(Requirement.parse("MyProject"),"sample.conf")
-
-The above code will obtain the filename of the "sample.conf" file in the data
-root of the "MyProject" distribution.
-
-Note, by the way, that this encapsulation of data files means that you can't
-actually install data files to some arbitrary location on a user's machine;
-this is a feature, not a bug.  You can always include a script in your
-distribution that extracts and copies your the documentation or data files to
-a user-specified location, at their discretion.  If you put related data files
-in a single directory, you can use ``resource_filename()`` with the directory
-name to get a filesystem directory that then can be copied with the ``shutil``
-module.  (Even if your package is installed as a zipfile, calling
-``resource_filename()`` on a directory will return an actual filesystem
-directory, whose contents will be that entire subtree of your distribution.)
-
-(Of course, if you're writing a new package, you can just as easily place your
-data files or directories inside one of your packages, rather than using the
-distutils' approach.  However, if you're updating an existing application, it
-may be simpler not to change the way it currently specifies these data files.)
+Historically, ``setuptools`` by way of ``easy_install`` would encapsulate data
+files from the distribution into the egg (see `the old docs
+<https://github.com/pypa/setuptools/blob/52aacd5b276fedd6849c3a648a0014f5da563e93/docs/setuptools.txt#L970-L1001>`_). As eggs are deprecated and pip-based installs
+fall back to the platform-specific location for installing data files, there is
+no supported facility to reliably retrieve these resources.
+
+Instead, the PyPA recommends that any data files you wish to be accessible at
+run time be included in the package.
 
 
 Automatic Resource Extraction
@@ -1173,130 +1223,53 @@ the quoted part.
 Distributing a ``setuptools``-based project
 ===========================================
 
-Using ``setuptools``...  Without bundling it!
----------------------------------------------
+Detailed instructions to distribute a setuptools project can be found at 
+`Packaging project tutorials`_.
 
-.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support.
+.. _Packaging project tutorials: https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives
 
-Your users might not have ``setuptools`` installed on their machines, or even
-if they do, it might not be the right version.  Fixing this is easy; just
-download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
-script.  (Be sure to add it to your revision control system, too.)  Then add
-these two lines to the very top of your setup script, before the script imports
-anything from setuptools:
+Before you begin, make sure you have the latest versions of setuptools and wheel::
 
-.. code-block:: python
+    python3 -m pip install --user --upgrade setuptools wheel
 
-    import ez_setup
-    ez_setup.use_setuptools()
+To build a setuptools project, run this command from the same directory where
+setup.py is located::
 
-That's it.  The ``ez_setup`` module will automatically download a matching
-version of ``setuptools`` from PyPI, if it isn't present on the target system.
-Whenever you install an updated version of setuptools, you should also update
-your projects' ``ez_setup.py`` files, so that a matching version gets installed
-on the target machine(s).
+    python3 setup.py sdist bdist_wheel
 
-By the way, setuptools supports the new PyPI "upload" command, so you can use
-``setup.py sdist upload`` or ``setup.py bdist_egg upload`` to upload your
-source or egg distributions respectively.  Your project's current version must
-be registered with PyPI first, of course; you can use ``setup.py register`` to
-do that.  Or you can do it all in one step, e.g. ``setup.py register sdist
-bdist_egg upload`` will register the package, build source and egg
-distributions, and then upload them both to PyPI, where they'll be easily
-found by other projects that depend on them.
+This will generate distribution archives in the `dist` directory.
 
-(By the way, if you need to distribute a specific version of ``setuptools``,
-you can specify the exact version and base download URL as parameters to the
-``use_setuptools()`` function.  See the function's docstring for details.)
+Before you upload the generated archives make sure you're registered on 
+https://test.pypi.org/account/register/. You will also need to verify your email
+to be able to upload any packages.
+You should install twine to be able to upload packages::
 
+    python3 -m pip install --user --upgrade setuptools wheel
 
-What Your Users Should Know
----------------------------
+Now, to upload these archives, run::
+
+    twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+To install your newly uploaded package ``example_pkg``,  you can use pip::
+
+    python3 -m pip install --index-url https://test.pypi.org/simple/ example_pkg
+
+If you have issues at any point, please refer to `Packaging project tutorials`_
+for clarification.
+
+Distributing legacy ``setuptools`` projects using ez_setup.py
+-------------------------------------------------------------
+
+.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support.
+
+Distributing packages using the legacy ``ez_setup.py`` and ``easy_install`` is 
+deprecated in favor of PIP. Please consider migrating to using pip and twine based
+distribution.
 
-In general, a setuptools-based project looks just like any distutils-based
-project -- as long as your users have an internet connection and are installing
-to ``site-packages``, that is.  But for some users, these conditions don't
-apply, and they may become frustrated if this is their first encounter with
-a setuptools-based project.  To keep these users happy, you should review the
-following topics in your project's installation instructions, if they are
-relevant to your project and your target audience isn't already familiar with
-setuptools and ``easy_install``.
-
-Network Access
-    If your project is using ``ez_setup``, you should inform users of the
-    need to either have network access, or to preinstall the correct version of
-    setuptools using the `EasyInstall installation instructions`_.  Those
-    instructions also have tips for dealing with firewalls as well as how to
-    manually download and install setuptools.
-
-Custom Installation Locations
-    You should inform your users that if they are installing your project to
-    somewhere other than the main ``site-packages`` directory, they should
-    first install setuptools using the instructions for `Custom Installation
-    Locations`_, before installing your project.
-
-Your Project's Dependencies
-    If your project depends on other projects that may need to be downloaded
-    from PyPI or elsewhere, you should list them in your installation
-    instructions, or tell users how to find out what they are.  While most
-    users will not need this information, any users who don't have unrestricted
-    internet access may have to find, download, and install the other projects
-    manually.  (Note, however, that they must still install those projects
-    using ``easy_install``, or your project will not know they are installed,
-    and your setup script will try to download them again.)
-
-    If you want to be especially friendly to users with limited network access,
-    you may wish to build eggs for your project and its dependencies, making
-    them all available for download from your site, or at least create a page
-    with links to all of the needed eggs.  In this way, users with limited
-    network access can manually download all the eggs to a single directory,
-    then use the ``-f`` option of ``easy_install`` to specify the directory
-    to find eggs in.  Users who have full network access can just use ``-f``
-    with the URL of your download page, and ``easy_install`` will find all the
-    needed eggs using your links directly.  This is also useful when your
-    target audience isn't able to compile packages (e.g. most Windows users)
-    and your package or some of its dependencies include C code.
-
-Revision Control System Users and Co-Developers
-    Users and co-developers who are tracking your in-development code using
-    a revision control system should probably read this manual's sections
-    regarding such development.  Alternately, you may wish to create a
-    quick-reference guide containing the tips from this manual that apply to
-    your particular situation.  For example, if you recommend that people use
-    ``setup.py develop`` when tracking your in-development code, you should let
-    them know that this needs to be run after every update or commit.
-
-    Similarly, if you remove modules or data files from your project, you
-    should remind them to run ``setup.py clean --all`` and delete any obsolete
-    ``.pyc`` or ``.pyo``.  (This tip applies to the distutils in general, not
-    just setuptools, but not everybody knows about them; be kind to your users
-    by spelling out your project's best practices rather than leaving them
-    guessing.)
-
-Creating System Packages
-    Some users want to manage all Python packages using a single package
-    manager, and sometimes that package manager isn't ``easy_install``!
-    Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
-    ``bdist_dumb`` formats for system packaging.  If a user has a locally-
-    installed "bdist" packaging tool that internally uses the distutils
-    ``install`` command, it should be able to work with ``setuptools``.  Some
-    examples of "bdist" formats that this should work with include the
-    ``bdist_nsi`` and ``bdist_msi`` formats for Windows.
-
-    However, packaging tools that build binary distributions by running
-    ``setup.py install`` on the command line or as a subprocess will require
-    modification to work with setuptools.  They should use the
-    ``--single-version-externally-managed`` option to the ``install`` command,
-    combined with the standard ``--root`` or ``--record`` options.
-    See the `install command`_ documentation below for more details.  The
-    ``bdist_deb`` command is an example of a command that currently requires
-    this kind of patching to work with setuptools.
-
-    If you or your users have a problem building a usable system package for
-    your project, please report the problem via the mailing list so that
-    either the "bdist" tool in question or setuptools can be modified to
-    resolve the issue.
+However, if you still have any ``ez_setup`` based packages, documentation for 
+ez_setup based distributions can be found at `ez_setup distribution guide`_.
 
+.. _ez_setup distribution guide: ez_setup.html
 
 Setting the ``zip_safe`` flag
 -----------------------------
@@ -1348,6 +1321,7 @@ then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
 flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to
 try to guess whether your project can work as a zipfile.
 
+.. _Namespace Packages:
 
 Namespace Packages
 ------------------
@@ -1520,22 +1494,11 @@ you use any option at all.
 Making your package available for EasyInstall
 ---------------------------------------------
 
-If you use the ``register`` command (``setup.py register``) to register your
-package with PyPI, that's most of the battle right there.  (See the
-`docs for the register command`_ for more details.)
-
-.. _docs for the register command: http://docs.python.org/dist/package-index.html
-
-If you also use the `upload`_ command to upload actual distributions of your
-package, that's even better, because EasyInstall will be able to find and
-download them directly from your project's PyPI page.
-
-However, there may be reasons why you don't want to upload distributions to
+There may be reasons why you don't want to upload distributions to
 PyPI, and just want your existing distributions (or perhaps a Subversion
 checkout) to be used instead.
 
-So here's what you need to do before running the ``register`` command.  There
-are three ``setup()`` arguments that affect EasyInstall:
+There are three ``setup()`` arguments that affect EasyInstall:
 
 ``url`` and ``download_url``
    These become links on your project's PyPI page.  EasyInstall will examine
@@ -1593,13 +1556,12 @@ 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 register upload
+    python 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, registering
-the project with PyPI, and uploading the files.  Thus, these commands will use
-the plain version from your ``setup.py``, without adding the build designation
-string.
+configured tag information, before creating source and binary eggs. Thus, these
+commands will use the plain version from your ``setup.py``, without adding the
+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.::
@@ -1608,36 +1570,50 @@ alias for this operation, e.g.::
 
 You can then use it like this::
 
-    python setup.py release sdist bdist_egg register upload
+    python 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.
 
 
 
-Distributing Extensions compiled with Pyrex
--------------------------------------------
+Distributing Extensions compiled with Cython
+--------------------------------------------
+
+``setuptools`` will detect at build time whether Cython is installed or not.
+If Cython is not found ``setuptools`` will ignore pyx files.
+
+To ensure Cython is available, include Cython in the build-requires section
+of your pyproject.toml::
+
+    [build-system]
+    requires=[..., 'cython']
 
-``setuptools`` includes transparent support for building Pyrex extensions, as
-long as you define your extensions using ``setuptools.Extension``, *not*
-``distutils.Extension``.  You must also not import anything from Pyrex in
-your setup script.
+Built with pip 10 or later, that declaration is sufficient to include Cython
+in the build. For broader compatibility, declare the dependency in your
+setup-requires of setup.cfg::
+
+    [options]
+    setup_requires =
+        ...
+        cython
+
+As long as Cython is present in the build environment, ``setuptools`` includes
+transparent support for building Cython extensions, as
+long as extensions are defined using ``setuptools.Extension``.
 
 If you follow these rules, you can safely list ``.pyx`` files as the source
-of your ``Extension`` objects in the setup script.  ``setuptools`` will detect
-at build time whether Pyrex is installed or not.  If it is, then ``setuptools``
-will use it.  If not, then ``setuptools`` will silently change the
-``Extension`` objects to refer to the ``.c`` counterparts of the ``.pyx``
-files, so that the normal distutils C compilation process will occur.
+of your ``Extension`` objects in the setup script.  If it is, then ``setuptools``
+will use it.
 
 Of course, for this to work, your source distributions must include the C
-code generated by Pyrex, as well as your original ``.pyx`` files.  This means
+code generated by Cython, as well as your original ``.pyx`` files.  This means
 that you will probably want to include current ``.c`` files in your revision
 control system, rebuilding them whenever you check changes in for the ``.pyx``
 source files.  This will ensure that people tracking your project in a revision
-control system will be able to build it even if they don't have Pyrex
+control system will be able to build it even if they don't have Cython
 installed, and that your source releases will be similarly usable with or
-without Pyrex.
+without Cython.
 
 
 -----------------
@@ -1924,11 +1900,11 @@ This command performs two operations: it updates a project's ``.egg-info``
 metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
 commands), and it allows you to temporarily change a project's version string,
 to support "daily builds" or "snapshot" releases.  It is run automatically by
-the ``sdist``, ``bdist_egg``, ``develop``, ``register``, 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 is used when you are building source distributions.)
+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
+is used when you are building source distributions.)
 
 In addition to writing the core egg metadata defined by ``setuptools`` and
 required by ``pkg_resources``, this command can be extended to write other
@@ -2002,60 +1978,14 @@ Creating a dated "nightly build" snapshot egg::
 
     python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
 
-Creating and uploading a release with no version tags, even if some default
-tags are specified in ``setup.cfg``::
+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 register upload
+    python 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.)
 
-
-.. _install command:
-
-``install`` - Run ``easy_install`` or old-style installation
-============================================================
-
-The setuptools ``install`` command is basically a shortcut to run the
-``easy_install`` command on the current project.  However, for convenience
-in creating "system packages" of setuptools-based projects, you can also
-use this option:
-
-``--single-version-externally-managed``
-    This boolean option tells the ``install`` command to perform an "old style"
-    installation, with the addition of an ``.egg-info`` directory so that the
-    installed project will still have its metadata available and operate
-    normally.  If you use this option, you *must* also specify the ``--root``
-    or ``--record`` options (or both), because otherwise you will have no way
-    to identify and remove the installed files.
-
-This option is automatically in effect when ``install`` is invoked by another
-distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
-will create system packages of eggs.  It is also automatically in effect if
-you specify the ``--root`` option.
-
-
-``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
-==============================================================================
-
-Setuptools runs this command as part of ``install`` operations that use the
-``--single-version-externally-managed`` options.  You should not invoke it
-directly; it is documented here for completeness and so that distutils
-extensions such as system package builders can make use of it.  This command
-has only one option:
-
-``--install-dir=DIR, -d DIR``
-    The parent directory where the ``.egg-info`` directory will be placed.
-    Defaults to the same as the ``--install-dir`` option specified for the
-    ``install_lib`` command, which is usually the system ``site-packages``
-    directory.
-
-This command assumes that the ``egg_info`` command has been given valid options
-via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
-command and use its options to locate the project's source ``.egg-info``
-directory.
-
-
 .. _rotate:
 
 ``rotate`` - Delete outdated distribution files
@@ -2254,25 +2184,16 @@ available:
 ``upload`` - Upload source and/or egg distributions to PyPI
 ===========================================================
 
+.. warning::
+    **upload** is deprecated in favor of using `twine
+    <https://pypi.org/p/twine>`_
+
 The ``upload`` command is implemented and `documented
 <https://docs.python.org/3.1/distutils/uploading.html>`_
 in distutils.
 
-Setuptools augments the ``upload`` command with support
-for `keyring <https://pypi.python.org/pypi/keyring>`_,
-allowing the password to be stored in a secure
-location and not in plaintext in the .pypirc file. To use
-keyring, first install keyring and set the password for
-the relevant repository, e.g.::
-
-    python -m keyring set <repository> <username>
-    Password for '<username>' in '<repository>': ********
-
-Then, in .pypirc, set the repository configuration as normal,
-but omit the password. Thereafter, uploads will use the
-password from the keyring.
-
 New in 20.1: Added keyring support.
+New in 40.0: Deprecated the upload command.
 
 
 -----------------------------------------
@@ -2287,7 +2208,7 @@ Configuring setup() using setup.cfg files
 
 ``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
 to define a package’s metadata and other options that are normally supplied
-to the ``setup()`` function.
+to the ``setup()`` function (declarative config).
 
 This approach not only allows automation scenarios but also reduces
 boilerplate code in some cases.
@@ -2323,6 +2244,9 @@ boilerplate code in some cases.
     scripts =
       bin/first.py
       bin/second.py
+    install_requires =
+      requests
+      importlib; python_version == "2.6"
 
     [options.package_data]
     * = *.txt, *.rst
@@ -2337,6 +2261,11 @@ boilerplate code in some cases.
         src.subpackage1
         src.subpackage2
 
+    [options.data_files]
+    /etc/my_package =
+        site.d/00_default.conf
+        host.d/00_default.conf
+    data = data/img/logo.png, data/svg/icon.svg
 
 Metadata and options are set in the config sections of the same name.
 
@@ -2359,12 +2288,41 @@ Metadata and options are set in the config sections of the same name.
 * In some cases, complex values can be provided in dedicated subsections for
   clarity.
 
-* Some keys allow ``file:``, ``attr:``, and ``find:`` directives in order to
-  cover common usecases.
+* Some keys allow ``file:``, ``attr:``, and ``find:`` and ``find_namespace:`` directives in
+  order to cover common usecases.
 
 * Unknown keys are ignored.
 
 
+Using a ``src/`` layout
+=======================
+
+One commonly used package configuration has all the module source code in a
+subdirectory (often called the ``src/`` layout), like this::
+
+    ├── src
+    │   └── mypackage
+    │       ├── __init__.py
+    │       └── mod1.py
+    ├── setup.py
+    └── setup.cfg
+
+You can set up your ``setup.cfg`` to automatically find all your packages in
+the subdirectory like this:
+
+.. code-block:: ini
+
+    # This example contains just the necessary options for a src-layout, set up
+    # the rest of the file as described above.
+
+    [options]
+    package_dir=
+        =src
+    packages=find:
+
+    [options.packages.find]
+    where=src
+
 Specifying values
 =================
 
@@ -2399,36 +2357,44 @@ Metadata
     The aliases given below are supported for compatibility reasons,
     but their use is not advised.
 
-==============================  =================  =====
-Key                             Aliases            Type
-==============================  =================  =====
+==============================  =================  =================  =============== =====
+Key                             Aliases            Type               Minimum Version Notes
+==============================  =================  =================  =============== =====
 name                                               str
-version                                            attr:, str
+version                                            attr:, file:, str  39.2.0          (1)
 url                             home-page          str
 download_url                    download-url       str
+project_urls                                       dict               38.3.0
 author                                             str
 author_email                    author-email       str
 maintainer                                         str
 maintainer_email                maintainer-email   str
 classifiers                     classifier         file:, list-comma
-license                                            file:, str
+license                                            str
 description                     summary            file:, str
 long_description                long-description   file:, str
-long_description_content_type                      str
+long_description_content_type                      str                38.6.0
 keywords                                           list-comma
 platforms                       platform           list-comma
 provides                                           list-comma
 requires                                           list-comma
 obsoletes                                          list-comma
-==============================  =================  =====
+==============================  =================  =================  =============== =====
 
+.. note::
+    A version loaded using the ``file:`` directive must comply with PEP 440.
+    It is easy to accidentally put something other than a valid version
+    string in such a file, so validation is stricter in this case.
+
+Notes:
+1. The `version` file attribute has only been supported since 39.2.0.
 
 Options
 -------
 
-=======================  =====
-Key                      Type
-=======================  =====
+=======================  ===================================  =============== =====
+Key                      Type                                 Minimum Version Notes
+=======================  ===================================  =============== =====
 zip_safe                 bool
 setup_requires           list-semi
 install_requires         list-semi
@@ -2444,21 +2410,25 @@ eager_resources          list-comma
 dependency_links         list-comma
 tests_require            list-semi
 include_package_data     bool
-packages                 find:, list-comma
+packages                 find:, find_namespace:, list-comma
 package_dir              dict
 package_data             section
 exclude_package_data     section
 namespace_packages       list-comma
 py_modules               list-comma
-=======================  =====
+data_files               dict                                 40.6.0
+=======================  ===================================  =============== =====
 
 .. note::
 
-    **packages** - The ``find:`` directive can be further configured
+    **packages** - The ``find:`` and ``find_namespace:`` directive can be further configured
     in a dedicated subsection ``options.packages.find``. This subsection
-    accepts the same keys as the `setuptools.find` function:
+    accepts the same keys as the `setuptools.find_packages` and the
+    `setuptools.find_namespace_packages` function:
     ``where``, ``include``, and ``exclude``.
 
+    **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
+
 
 Configuration API
 =================
@@ -2652,8 +2622,8 @@ Adding Support for Revision Control Systems
 If the files you want to include in the source distribution are tracked using
 Git, Mercurial or SVN, you can use the following packages to achieve that:
 
-- Git and Mercurial: `setuptools_scm <https://pypi.python.org/pypi/setuptools_scm>`_
-- SVN: `setuptools_svn <https://pypi.python.org/pypi/setuptools_svn>`_
+- Git and Mercurial: `setuptools_scm <https://pypi.org/project/setuptools_scm/>`_
+- SVN: `setuptools_svn <https://pypi.org/project/setuptools_svn/>`_
 
 If you would like to create a plugin for ``setuptools`` to find files tracked
 by another revision control system, you can do so by adding an entry point to