Merge branch 'master' into feature/2093-docs-revampfeature/2093-docs-revamp

8 files changed, 122 insertions, 31 deletions

diff --git a/docs/conf.py b/docs/conf.py
index b92b50cc..12520586 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -101,7 +101,7 @@ link_files = {
                 url='http://bugs.jython.org/issue{jython}',
             ),
             dict(
-                pattern=r'Python #(?P<python>\d+)',
+                pattern=r'(Python #|bpo-)(?P<python>\d+)',
                 url='http://bugs.python.org/issue{python}',
             ),
             dict(
@@ -129,6 +129,10 @@ link_files = {
                 url='{GH}/jaraco/setuptools_svn/issues/{setuptools_svn}',
             ),
             dict(
+                pattern=r'pypa/distutils#(?P<distutils>\d+)',
+                url='{GH}/pypa/distutils/issues/{distutils}',
+            ),
+            dict(
                 pattern=r'^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n',
                 with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
             ),
diff --git a/docs/deprecated/distutils-legacy.txt b/docs/deprecated/distutils-legacy.txt
new file mode 100644
index 00000000..a5d96260
--- /dev/null
+++ b/docs/deprecated/distutils-legacy.txt
@@ -0,0 +1,25 @@
+Porting from Distutils
+======================
+
+Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils.
+
+Since the 49.1.2 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is disabled by default. To enable the use of this copy of distutils when invoking setuptools, set the enviroment variable:
+
+	SETUPTOOLS_USE_DISTUTILS=local
+
+This behavior is planned to become the default.
+
+Prefer Setuptools
+-----------------
+
+As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements.
+
+``distutils.core.setup`` → ``setuptools.setup``
+
+``distutils.cmd.Command`` → ``setuptools.Command``
+
+``distutils.log`` → (no replacement yet)
+
+``distutils.version.*`` → ``packaging.version.*``
+
+If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported.
diff --git a/docs/deprecated/index.txt b/docs/deprecated/index.txt
index bb6579f8..a655b219 100644
--- a/docs/deprecated/index.txt
+++ b/docs/deprecated/index.txt
@@ -16,4 +16,4 @@ objectives.
     python3
     python_eggs
     easy_install
-
+    distutils-legacy
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
index e6171e4e..e84cd640 100644
--- a/docs/developer-guide.txt
+++ b/docs/developer-guide.txt
@@ -23,16 +23,16 @@ contribution.
 Project Management
 ------------------
 
-Setuptools is maintained primarily in Github at `this home
+Setuptools is maintained primarily in GitHub at `this home
 <https://github.com/pypa/setuptools>`_. Setuptools is maintained under the
 Python Packaging Authority (PyPA) with several core contributors. All bugs
-for Setuptools are filed and the canonical source is maintained in Github.
+for Setuptools are filed and the canonical source is maintained in GitHub.
 
 User support and discussions are done through the issue tracker (for specific)
-issues, through the distutils-sig mailing list, or on IRC (Freenode) at
+issues, through the `distutils-sig mailing list <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_, or on IRC (Freenode) at
 #pypa.
 
-Discussions about development happen on the pypa-dev mailing list or on
+Discussions about development happen on the distutils-sig mailing list or on
 `Gitter <https://gitter.im/pypa/setuptools>`_.
 
 -----------------
@@ -44,7 +44,7 @@ describing the motivation behind making changes. First search to see if a
 ticket already exists for your issue. If not, create one. Try to think from
 the perspective of the reader. Explain what behavior you expected, what you
 got instead, and what factors might have contributed to the unexpected
-behavior. In Github, surround a block of code or traceback with the triple
+behavior. In GitHub, surround a block of code or traceback with the triple
 backtick "\`\`\`" so that it is formatted nicely.
 
 Filing a ticket provides a forum for justification, discussion, and
@@ -145,5 +145,5 @@ setuptools from source. Eventually, this limitation may be lifted as
 PEP 517/518 reach ubiquitous adoption, but for now, Setuptools
 cannot declare dependencies other than through
 ``setuptools/_vendor/vendored.txt`` and
-``pkg_reosurces/_vendor/vendored.txt`` and refreshed by way of
+``pkg_resources/_vendor/vendored.txt`` and refreshed by way of
 ``paver update_vendored`` (pavement.py).
diff --git a/docs/index.txt b/docs/index.txt
index fda2e948..5a460526 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,15 +1,8 @@
-Welcome to Setuptools' documentation!
-=====================================
+Documentation
+=============
 
 Setuptools is a fully-featured, actively-maintained, and stable library
-designed to facilitate packaging Python projects, where packaging includes:
-
- - Python package and module definitions
- - Distribution package metadata
- - Test hooks
- - Project installation
- - Platform-specific details
- - Python 3 support
+designed to facilitate packaging Python projects.
 
 Documentation content:
 
diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt
index 71568c1a..7d0d8da9 100644
--- a/docs/pkg_resources.txt
+++ b/docs/pkg_resources.txt
@@ -594,7 +594,7 @@ Requirements Parsing
 
         FooProject >= 1.2
         Fizzy [foo, bar]
-        PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1
+        PickyThing>1.6,<=1.9,!=1.8.6
         SomethingWhoseVersionIDontCareAbout
         SomethingWithMarker[foo]>1.0;python_version<"2.7"
 
@@ -1596,12 +1596,12 @@ Parsing Utilities
     See ``to_filename()``.
 
 ``safe_version(version)``
-    This will return the normalized form of any PEP 440 version, if the version
-    string is not PEP 440 compatible than it is similar to ``safe_name()``
-    except that spaces in the input become dots, and dots are allowed to exist
-    in the output.  As with ``safe_name()``, if you are generating a filename
-    from this you should replace any "-" characters in the output with
-    underscores.
+    This will return the normalized form of any PEP 440 version. If the version
+    string is not PEP 440 compatible, this function behaves similar to
+    ``safe_name()`` except that spaces in the input become dots, and dots are
+    allowed to exist in the output.  As with ``safe_name()``, if you are
+    generating a filename from this you should replace any "-" characters in
+    the output with underscores.
 
 ``safe_extra(extra)``
     Return a "safe" form of an extra's name, suitable for use in a requirement
diff --git a/docs/python 2 sunset.txt b/docs/python 2 sunset.txt
new file mode 100644
index 00000000..f7b7ee25
--- /dev/null
+++ b/docs/python 2 sunset.txt
@@ -0,0 +1,69 @@
+:orphan:
+
+Python 2 Sunset
+===============
+
+Since January 2020 and the release of Setuptools 45, Python 2 is no longer
+supported by the most current release (`discussion
+<https://github.com/pypa/setuptools/issues/1458>`_). Setuptools as a project
+continues to support Python 2 with bugfixes and important features on
+Setuptools 44.x.
+
+By design, most users will be unaffected by this change. That's because
+Setuptools 45 declares its supported Python versions to exclude Python 2.7,
+and installers such as pip 9 or later will honor this declaration and prevent
+installation of Setuptools 45 or later in Python 2 environments.
+
+Users that do import any portion of Setuptools 45 or later on Python 2 are
+directed to this documentation to provide guidance on how to work around the
+issues.
+
+Workarounds
+-----------
+
+The best recommendation is to avoid Python 2 and move to Python 3 where
+possible. This project acknowledges that not all environments can drop Python
+2 support, so provides other options.
+
+In less common scenarios, later versions of Setuptools can be installed on
+unsupported Python versions. In these environments, the installer is advised
+to first install ``setuptools<45`` to "pin Setuptools" to a compatible
+version.
+
+- When using older versions of pip (before 9.0), the ``Requires-Python``
+  directive is not honored and invalid versions can be installed. Users are
+  advised first to upgrade pip and retry or to pin Setuptools. Use ``pip
+  --version`` to determine the version of pip.
+- When using ``easy_install``, ``Requires-Python`` is not honored and later
+  versions can be installed. In this case, users are advised to pin
+  Setuptools. This applies to ``setup.py install`` invocations as well, as
+  they use Setuptools under the hood.
+
+It's still not working
+----------------------
+
+If after trying the above steps, the Python environment still has incompatible
+versions of Setuptools installed, here are some things to try.
+
+1. Uninstall and reinstall Setuptools. Run ``pip uninstall -y setuptools`` for
+   the relevant environment. Repeat until there is no Setuptools installed.
+   Then ``pip install setuptools``.
+2. If possible, attempt to replicate the problem in a second environment
+   (virtual machine, friend's computer, etc). If the issue is isolated to just
+   one unique enviornment, first determine what is different about those
+   environments (or reinstall/reset the failing one to defaults).
+3. End users who are not themselves the maintainers for the package they are
+   trying to install should contact the support channels for the relevant
+   application. Please be considerate of those projects by searching for
+   existing issues and following the latest guidance before reaching out for
+   support. When filing an issue, be sure to give as much detail as possible
+   to help the maintainers understand what factors led to the issue after
+   following their recommended guidance.
+4. Reach out to your local support groups. There's a good chance someone
+   nearby has the expertise and willingness to help.
+5. If all else fails, `file this template
+   <https://github.com/pypa/setuptools/issues/new?assignees=&labels=Python+2&template=setuptools-warns-about-python-2-incompatibility.md&title=Incompatible+install+in+(summarize+your+environment)>`_
+   with Setuptools. Please complete the whole template, providing as much
+   detail about what factors led to the issue. Setuptools maintainers will
+   summarily close tickets filed without any meaningful detail or engagement
+   with the issue.
diff --git a/docs/userguide/declarative_config.txt b/docs/userguide/declarative_config.txt
index 2aa1c717..51c897c4 100644
--- a/docs/userguide/declarative_config.txt
+++ b/docs/userguide/declarative_config.txt
@@ -46,11 +46,11 @@ boilerplate code in some cases.
     include_package_data = True
     packages = find:
     scripts =
-      bin/first.py
-      bin/second.py
+        bin/first.py
+        bin/second.py
     install_requires =
-      requests
-      importlib; python_version == "2.6"
+        requests
+        importlib; python_version == "2.6"
 
     [options.package_data]
     * = *.txt, *.rst
@@ -86,8 +86,8 @@ Metadata and options are set in the config sections of the same name.
 
       [metadata]
       keywords =
-        one
-        two
+          one
+          two
 
 * In some cases, complex values can be provided in dedicated subsections for
   clarity.