Merge pull request #1862 from benoit-pierre/drop-ez_setup-documentation

docs: drop ez_setup documentation and related references

4 files changed, 4 insertions, 225 deletions

diff --git a/changelog.d/1862.doc.rst b/changelog.d/1862.doc.rst
new file mode 100644
index 00000000..b71583ba
--- /dev/null
+++ b/changelog.d/1862.doc.rst
@@ -0,0 +1 @@
+Drop ez_setup documentation: deprecated for some time (last updated in 2016), and still relying on easy_install (deprecated too).
diff --git a/docs/easy_install.txt b/docs/easy_install.txt
index aa11f890..e247d8fd 100644
--- a/docs/easy_install.txt
+++ b/docs/easy_install.txt
@@ -317,8 +317,8 @@ Note that instead of changing your ``PATH`` to include the Python scripts
 directory, you can also retarget the installation location for scripts so they
 go on a directory that's already on the ``PATH``.  For more information see
 `Command-Line Options`_ and `Configuration Files`_.  During installation,
-pass command line options (such as ``--script-dir``) to
-``ez_setup.py`` to control where ``easy_install.exe`` will be installed.
+pass command line options (such as ``--script-dir``) to to control where
+scripts will be installed.
 
 
 Windows Executable Launcher
diff --git a/docs/ez_setup.txt b/docs/ez_setup.txt
deleted file mode 100644
index 0126fee3..00000000
--- a/docs/ez_setup.txt
+++ /dev/null
@@ -1,195 +0,0 @@
-: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/setuptools.txt b/docs/setuptools.txt
index b3852232..3c6243e2 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -8,14 +8,7 @@ distribute Python packages, especially ones that have dependencies on other
 packages.
 
 Packages built and distributed using ``setuptools`` look to the user like
-ordinary Python packages based on the ``distutils``.  Your users don't need to
-install or even know about setuptools in order to use them, and you don't
-have to include the entire setuptools package in your distributions.  By
-including just a single `bootstrap module`_ (a 12K .py file), your package will
-automatically download and install ``setuptools`` if the user is building your
-package from source and doesn't have a suitable version already installed.
-
-.. _bootstrap module: https://bootstrap.pypa.io/ez_setup.py
+ordinary Python packages based on the ``distutils``.
 
 Feature Highlights:
 
@@ -56,8 +49,6 @@ Feature Highlights:
 
 .. contents:: **Table of Contents**
 
-.. _ez_setup.py: `bootstrap module`_
-
 
 -----------------
 Developer's Guide
@@ -590,10 +581,6 @@ Python must be available via the ``PATH`` environment variable, under its
 "long" name.  That is, if the egg is built for Python 2.3, there must be a
 ``python2.3`` executable present in a directory on ``PATH``.
 
-This feature is primarily intended to support ez_setup the installation of
-setuptools itself on non-Windows platforms, but may also be useful for other
-projects as well.
-
 IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
 invoked via symlinks.  They *must* be invoked using their original filename, in
 order to ensure that, once running, ``pkg_resources`` will know what project
@@ -1254,20 +1241,6 @@ To install your newly uploaded package ``example_pkg``,  you can use pip::
 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.
-
-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
 -----------------------------