In the documentation, update references to point at `setuptools`. (GH-3456)

While the directives in the source files are still called `distutils`, the [Python upstream documentation](https://docs.python.org/3/library/distutils.html) does not
recommend using distutils anymore, and rather points at setuptools, so avoid confusing new users by providing confusing legacy usage examples.

Also, this corrects one example in which Extension is imported too late, and would cause annoying errors when running `setup.py`.

15 files changed, 64 insertions, 72 deletions

diff --git a/docs/examples/quickstart/build/setup.py b/docs/examples/quickstart/build/setup.py
index 201a1aa18..fe959a106 100644
--- a/docs/examples/quickstart/build/setup.py
+++ b/docs/examples/quickstart/build/setup.py
@@ -1,5 +1,8 @@
-from distutils.core import setup
+from setuptools import setup
 from Cython.Build import cythonize
 
-setup(name='Hello world app',
-      ext_modules=cythonize("hello.pyx"))
+setup(
+    name='Hello world app',
+    ext_modules=cythonize("hello.pyx"),
+    zip_safe=False,
+)
diff --git a/docs/examples/tutorial/cython_tutorial/setup.py b/docs/examples/tutorial/cython_tutorial/setup.py
index 302a08e5f..45941a33c 100644
--- a/docs/examples/tutorial/cython_tutorial/setup.py
+++ b/docs/examples/tutorial/cython_tutorial/setup.py
@@ -1,4 +1,4 @@
-from distutils.core import setup
+from setuptools import setup
 from Cython.Build import cythonize
 
 setup(
diff --git a/docs/examples/tutorial/external/setup.py b/docs/examples/tutorial/external/setup.py
index 8584c5d29..289bc9534 100644
--- a/docs/examples/tutorial/external/setup.py
+++ b/docs/examples/tutorial/external/setup.py
@@ -1,5 +1,4 @@
-from distutils.core import setup
-from distutils.extension import Extension
+from setuptools import Extension, setup
 from Cython.Build import cythonize
 
 ext_modules = [
diff --git a/docs/examples/userguide/parallelism/setup.py b/docs/examples/userguide/parallelism/setup.py
index 8bafef363..fe6d0a64c 100644
--- a/docs/examples/userguide/parallelism/setup.py
+++ b/docs/examples/userguide/parallelism/setup.py
@@ -1,5 +1,4 @@
-from distutils.core import setup
-from distutils.extension import Extension
+from setuptools import Extension, setup
 from Cython.Build import cythonize
 
 ext_modules = [
diff --git a/docs/examples/userguide/sharing_declarations/setup.py b/docs/examples/userguide/sharing_declarations/setup.py
index b915d0a41..505b53e9d 100644
--- a/docs/examples/userguide/sharing_declarations/setup.py
+++ b/docs/examples/userguide/sharing_declarations/setup.py
@@ -1,4 +1,4 @@
-from distutils.core import setup
+from setuptools import setup
 from Cython.Build import cythonize
 
 setup(ext_modules=cythonize(["landscaping.pyx", "shrubbing.pyx"]))
diff --git a/docs/examples/userguide/wrapping_CPlusPlus/setup.py b/docs/examples/userguide/wrapping_CPlusPlus/setup.py
index 0c89865d6..09009d28d 100644
--- a/docs/examples/userguide/wrapping_CPlusPlus/setup.py
+++ b/docs/examples/userguide/wrapping_CPlusPlus/setup.py
@@ -1,4 +1,4 @@
-from distutils.core import setup
+from setuptools import setup
 
 from Cython.Build import cythonize
 
diff --git a/docs/src/quickstart/build.rst b/docs/src/quickstart/build.rst
index 47d6168ce..cf0f7d74c 100644
--- a/docs/src/quickstart/build.rst
+++ b/docs/src/quickstart/build.rst
@@ -8,18 +8,18 @@ Cython code must, unlike Python, be compiled. This happens in two stages:
  - The ``.c`` file is compiled by a C compiler to
    a ``.so`` file (or ``.pyd`` on Windows) which can be
    ``import``-ed directly into a Python session.
-   Distutils or setuptools take care of this part.
+   `setuptools <https://setuptools.readthedocs.io/>`_ takes care of this part.
    Although Cython can call them for you in certain cases.
-
-To understand fully the Cython + distutils/setuptools build process,
+   
+To understand fully the Cython + setuptools build process,
 one may want to read more about
 `distributing Python modules <https://docs.python.org/3/distributing/index.html>`_.
 
 There are several ways to build Cython code:
 
- - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way.
+ - Write a setuptools ``setup.py``. This is the normal and recommended way.
  - Use :ref:`Pyximport<pyximport>`, importing Cython ``.pyx`` files as if they
-   were ``.py`` files (using distutils to compile and build in the background).
+   were ``.py`` files (using setuptools to compile and build in the background).
    This method is easier than writing a ``setup.py``, but is not very flexible.
    So you'll need to write a ``setup.py`` if, for example, you need certain compilations options.
  - Run the ``cython`` command-line utility manually to produce the ``.c`` file
@@ -30,11 +30,11 @@ There are several ways to build Cython code:
    both of which allow Cython code inline.
    This is the easiest way to get started writing Cython code and running it.
 
-Currently, using distutils or setuptools is the most common way Cython files are built and distributed.
+Currently, using setuptools is the most common way Cython files are built and distributed.
 The other methods are described in more detail in the :ref:`compilation` section of the reference manual.
 
 
-Building a Cython module using distutils
+Building a Cython module using setuptools
 ----------------------------------------
 
 Imagine a simple "hello world" script in a file ``hello.pyx``:
@@ -49,11 +49,10 @@ To build, run ``python setup.py build_ext --inplace``.  Then simply
 start a Python session and do ``from hello import say_hello_to`` and
 use the imported function as you see fit.
 
-One caveat if you use setuptools instead of distutils, the default
-action when running ``python setup.py install`` is to create a zipped
-``egg`` file which will not work with ``cimport`` for ``pxd`` files
-when you try to use them from a dependent package.
-To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
+One caveat: the default action when running ``python setup.py install`` is to
+create a zipped ``egg`` file which will not work with ``cimport`` for ``pxd``
+files when you try to use them from a dependent package.  To prevent this,
+include ``zip_safe=False`` in the arguments to ``setup()``.
 
 .. _jupyter-notebook:
 
diff --git a/docs/src/tutorial/clibraries.rst b/docs/src/tutorial/clibraries.rst
index dd91d9ef2..ff0a7b9d3 100644
--- a/docs/src/tutorial/clibraries.rst
+++ b/docs/src/tutorial/clibraries.rst
@@ -180,11 +180,10 @@ Compiling and linking
 =====================
 
 At this point, we have a working Cython module that we can test.  To
-compile it, we need to configure a ``setup.py`` script for distutils.
+compile it, we need to configure a ``setup.py`` script for setuptools.
 Here is the most basic script for compiling a Cython module::
 
-    from distutils.core import setup
-    from distutils.extension import Extension
+    from setuptools import Extension, setup
     from Cython.Build import cythonize
 
     setup(
@@ -193,7 +192,7 @@ Here is the most basic script for compiling a Cython module::
 
 
 To build against the external C library, we need to make sure Cython finds the necessary libraries.
-There are two ways to archive this. First we can tell distutils where to find
+There are two ways to archive this. First we can tell setuptools where to find
 the c-source to compile the :file:`queue.c` implementation automatically. Alternatively,
 we can build and install C-Alg as system library and dynamically link it. The latter is useful
 if other applications also use C-Alg.
@@ -221,7 +220,7 @@ To build the c-code automatically we need to include compiler directives in `que
                 cqueue.queue_free(self._c_queue)
 
 The ``sources`` compiler directive gives the path of the C
-files that distutils is going to compile and
+files that setuptools is going to compile and
 link (statically) into the resulting extension module.
 In general all relevant header files should be found in ``include_dirs``.
 Now we can build the project using::
diff --git a/docs/src/tutorial/cython_tutorial.rst b/docs/src/tutorial/cython_tutorial.rst
index f80a8b016..45d0d8e85 100644
--- a/docs/src/tutorial/cython_tutorial.rst
+++ b/docs/src/tutorial/cython_tutorial.rst
@@ -40,7 +40,7 @@ Save this code in a file named :file:`helloworld.pyx`.  Now we need to create
 the :file:`setup.py`, which is like a python Makefile (for more information
 see :ref:`compilation`). Your :file:`setup.py` should look like::
 
-    from distutils.core import setup
+    from setuptools import setup
     from Cython.Build import cythonize
 
     setup(
@@ -273,7 +273,7 @@ compile it with Cython (without changing the code). We will also change the name
 file to ``example_py_cy.py`` to differentiate it from the others.
 Now the ``setup.py`` looks like this::
 
-    from distutils.core import setup
+    from setuptools import setup
     from Cython.Build import cythonize
 
     setup(
diff --git a/docs/src/tutorial/external.rst b/docs/src/tutorial/external.rst
index b55b96505..42b1ed0c2 100644
--- a/docs/src/tutorial/external.rst
+++ b/docs/src/tutorial/external.rst
@@ -41,7 +41,7 @@ Dynamic linking
 The libc math library is special in that it is not linked by default
 on some Unix-like systems, such as Linux. In addition to cimporting the
 declarations, you must configure your build system to link against the
-shared library ``m``.  For distutils, it is enough to add it to the
+shared library ``m``.  For setuptools, it is enough to add it to the
 ``libraries`` parameter of the ``Extension()`` setup:
 
 .. literalinclude:: ../../examples/tutorial/external/setup.py
diff --git a/docs/src/userguide/debugging.rst b/docs/src/userguide/debugging.rst
index 06af18bbf..a77e97ad1 100644
--- a/docs/src/userguide/debugging.rst
+++ b/docs/src/userguide/debugging.rst
@@ -25,15 +25,14 @@ The debugger will need debug information that the Cython compiler can export.
 This can be achieved from within the setup script by passing ``gdb_debug=True``
 to ``cythonize()``::
 
-    from distutils.core import setup
-    from distutils.extension import Extension
+    from setuptools import Extension, setup
 
     extensions = [Extension('source', ['source.pyx'])]
 
     setup(..., ext_modules=cythonize(extensions, gdb_debug=True))
 
 For development it's often helpful to pass the ``--inplace`` flag to
-the ``setup.py`` script, which makes distutils build your project
+the ``setup.py`` script, which makes setuptools build your project
 "in place", i.e., not in a separate `build` directory.
 
 When invoking Cython from the command line directly you can have it write
diff --git a/docs/src/userguide/numpy_pythran.rst b/docs/src/userguide/numpy_pythran.rst
index 5ec4b46d1..e83e2698b 100644
--- a/docs/src/userguide/numpy_pythran.rst
+++ b/docs/src/userguide/numpy_pythran.rst
@@ -16,7 +16,7 @@ This can lead to really interesting speedup in some cases, going from 2 up to
 
 Please note that this feature is experimental.
 
-Usage example with distutils
+Usage example with setuptools
 ----------------------------
 
 You first need to install Pythran. See its `documentation
@@ -25,11 +25,11 @@ You first need to install Pythran. See its `documentation
 Then, simply add a ``cython: np_pythran=True`` directive at the top of the
 Python files that needs to be compiled using Pythran numpy support.
 
-Here is an example of a simple ``setup.py`` file using distutils:
+Here is an example of a simple ``setup.py`` file using setuptools:
 
 .. code::
 
-  from distutils.core import setup
+  from setuptools import setup
   from Cython.Build import cythonize
 
   setup(
diff --git a/docs/src/userguide/numpy_tutorial.rst b/docs/src/userguide/numpy_tutorial.rst
index 20683668e..a89cf86e2 100644
--- a/docs/src/userguide/numpy_tutorial.rst
+++ b/docs/src/userguide/numpy_tutorial.rst
@@ -73,7 +73,7 @@ However there are several options to automate these steps:
 3. A version of pyximport is shipped with Cython,
    so that you can import pyx-files dynamically into Python and
    have them compiled automatically (See :ref:`pyximport`).
-4. Cython supports distutils so that you can very easily create build scripts
+4. Cython supports setuptools so that you can very easily create build scripts
    which automate the process, this is the preferred method for
    Cython implemented libraries and packages.
    See :ref:`Basic setup.py <basic_setup.py>`.
diff --git a/docs/src/userguide/source_files_and_compilation.rst b/docs/src/userguide/source_files_and_compilation.rst
index 3a4d38ca2..6f15cd8d2 100644
--- a/docs/src/userguide/source_files_and_compilation.rst
+++ b/docs/src/userguide/source_files_and_compilation.rst
@@ -53,7 +53,7 @@ compiled with the C compiler using whatever options are appropriate on your
 platform for generating an extension module. For these options look at the
 official Python documentation.
 
-The other, and probably better, way is to use the :mod:`distutils` extension
+The other, and probably better, way is to use the :mod:`setuptools` extension
 provided with Cython. The benefit of this method is that it will give the
 platform specific compilation options, acting like a stripped down autotools.
 
@@ -93,7 +93,7 @@ to libraries you want to link with.)
 After compilation, a ``yourmod.so`` (:file:`yourmod.pyd` for Windows)
 file is written into the target directory
 and your module, ``yourmod``, is available for you to import as with any other
-Python module.  Note that if you are not relying on ``cythonize`` or distutils,
+Python module.  Note that if you are not relying on ``cythonize`` or setuptools,
 you will not automatically benefit from the platform specific file extension
 that CPython generates for disambiguation, such as
 ``yourmod.cpython-35m-x86_64-linux-gnu.so`` on a regular 64bit Linux installation
@@ -103,23 +103,22 @@ of CPython 3.5.
 
 Basic setup.py
 ===============
-The distutils extension provided with Cython allows you to pass ``.pyx`` files
+The setuptools extension provided with Cython allows you to pass ``.pyx`` files
 directly to the ``Extension`` constructor in your setup file.
 
 If you have a single Cython file that you want to turn into a compiled
 extension, say with filename :file:`example.pyx` the associated :file:`setup.py`
 would be::
 
-    from distutils.core import setup
+    from setuptools import setup
     from Cython.Build import cythonize
 
     setup(
         ext_modules = cythonize("example.pyx")
     )
 
-To understand the :file:`setup.py` more fully look at the official
-:mod:`distutils` documentation. To compile the extension for use in the
-current directory use:
+To understand the :file:`setup.py` more fully look at the official `setuptools
+documentation`_. To compile the extension for use in the current directory use:
 
 .. sourcecode:: text
 
@@ -131,7 +130,7 @@ Configuring the C-Build
 If you have include files in non-standard places you can pass an
 ``include_path`` parameter to ``cythonize``::
 
-    from distutils.core import setup
+    from setuptools import setup
     from Cython.Build import cythonize
 
     setup(
@@ -162,8 +161,7 @@ linker options you will need to create ``Extension`` instances manually
 (note that glob syntax can still be used to specify multiple extensions
 in one line)::
 
-    from distutils.core import setup
-    from distutils.extension import Extension
+    from setuptools import Extension, setup
     from Cython.Build import cythonize
 
     extensions = [
@@ -182,11 +180,10 @@ in one line)::
         ext_modules=cythonize(extensions),
     )
 
-Note that when using setuptools, you should import it before Cython as
-setuptools may replace the ``Extension`` class in distutils.  Otherwise,
+Note that when using setuptools, you should import it before Cython, otherwise,
 both might disagree about the class to use here.
 
-Note also that if you use setuptools instead of distutils, the default
+Note also that if you use setuptools instead of :mod:`distutils`, the default
 action when running ``python setup.py install`` is to create a zipped
 ``egg`` file which will not work with ``cimport`` for ``pxd`` files
 when you try to use them from a dependent package.
@@ -204,7 +201,7 @@ merges the list of libraries, so this works as expected (similarly
 with other options, like ``include_dirs`` above).
 
 If you have some C files that have been wrapped with Cython and you want to
-compile them into your extension, you can define the distutils ``sources``
+compile them into your extension, you can define the setuptools ``sources``
 parameter::
 
     # distutils: sources = helper.c, another_helper.c
@@ -213,9 +210,8 @@ Note that these sources are added to the list of sources of the current
 extension module.  Spelling this out in the :file:`setup.py` file looks
 as follows::
 
-    from distutils.core import setup
+    from setuptools import Extension, setup
     from Cython.Build import cythonize
-    from distutils.extension import Extension
 
     sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
 
@@ -226,14 +222,14 @@ as follows::
     )
 
 The :class:`Extension` class takes many options, and a fuller explanation can
-be found in the `distutils documentation`_. Some useful options to know about
+be found in the `setuptools documentation`_. Some useful options to know about
 are ``include_dirs``, ``libraries``, and ``library_dirs`` which specify where
 to find the ``.h`` and library files when linking to external libraries.
 
-.. _distutils documentation: https://docs.python.org/extending/building.html
+.. _setuptools documentation: https://setuptools.readthedocs.io/
 
 Sometimes this is not enough and you need finer customization of the
-distutils :class:`Extension`.
+setuptools :class:`Extension`.
 To do this, you can provide a custom function ``create_extension``
 to create the final :class:`Extension` object after Cython has processed
 the sources, dependencies and ``# distutils`` directives but before the
@@ -329,11 +325,10 @@ doesn't want to use it just to install your module. Also, the installed version
 may not be the same one you used, and may not compile your sources correctly.
 
 This simply means that the :file:`setup.py` file that you ship with will just
-be a normal distutils file on the generated `.c` files, for the basic example
+be a normal setuptools file on the generated `.c` files, for the basic example
 we would have instead::
 
-    from distutils.core import setup
-    from distutils.extension import Extension
+    from setuptools import Extension, setup
 
     setup(
         ext_modules = [Extension("example", ["example.c"])]
@@ -342,8 +337,7 @@ we would have instead::
 This is easy to combine with :func:`cythonize` by changing the file extension
 of the extension module sources::
 
-    from distutils.core import setup
-    from distutils.extension import Extension
+    from setuptools import Extension, setup
 
     USE_CYTHON = ...   # command line option, try-import, ...
 
@@ -522,7 +516,7 @@ glob must be on a separate line.  Pyximport will check the file date for each
 of those files before deciding whether to rebuild the module.  In order to
 keep track of the fact that the dependency has been handled, Pyximport updates
 the modification time of your ".pyx" source file.  Future versions may do
-something more sophisticated like informing distutils of the dependencies
+something more sophisticated like informing setuptools of the dependencies
 directly.
 
 
@@ -538,7 +532,7 @@ compiled.  Usually the defaults are fine.  You might run into problems if
 you wanted to write your program in half-C, half-Cython and build them
 into a single library.
 
-Pyximport does not hide the Distutils/GCC warnings and errors generated
+Pyximport does not hide the setuptools/GCC warnings and errors generated
 by the import process.  Arguably this will give you better feedback if
 something went wrong and why.  And if nothing went wrong it will give you
 the warm fuzzy feeling that pyximport really did rebuild your module as it
@@ -662,7 +656,7 @@ Compiler options
 Compiler options can be set in the :file:`setup.py`, before calling :func:`cythonize`,
 like this::
 
-    from distutils.core import setup
+    from setuptools import setup
 
     from Cython.Build import cythonize
     from Cython.Compiler import Options
@@ -809,7 +803,7 @@ Cython code.  Here is the list of currently supported directives:
     into the compiled C code.  This also enables profiling.  Default is
     False.  Note that the generated module will not actually use line
     tracing, unless you additionally pass the C macro definition
-    ``CYTHON_TRACE=1`` to the C compiler (e.g. using the distutils option
+    ``CYTHON_TRACE=1`` to the C compiler (e.g. using the setuptools option
     ``define_macros``).  Define ``CYTHON_TRACE_NOGIL=1`` to also include
     ``nogil`` functions and sections.
 
@@ -980,7 +974,7 @@ In :file:`setup.py`
 Compiler directives can also be set in the :file:`setup.py` file by passing a keyword
 argument to ``cythonize``::
 
-    from distutils.core import setup
+    from setuptools import setup
     from Cython.Build import cythonize
 
     setup(
diff --git a/docs/src/userguide/wrapping_CPlusPlus.rst b/docs/src/userguide/wrapping_CPlusPlus.rst
index e12bf38be..fca022fbb 100644
--- a/docs/src/userguide/wrapping_CPlusPlus.rst
+++ b/docs/src/userguide/wrapping_CPlusPlus.rst
@@ -97,7 +97,7 @@ We use the lines::
         pass
 
 to include the C++ code from :file:`Rectangle.cpp`. It is also possible to specify to
-distutils that :file:`Rectangle.cpp` is a source. To do that, you can add this directive at the
+setuptools that :file:`Rectangle.cpp` is a source. To do that, you can add this directive at the
 top of the ``.pyx`` (not ``.pxd``) file::
 
     # distutils: sources = Rectangle.cpp
@@ -527,7 +527,7 @@ Specify C++ language in setup.py
 Instead of specifying the language and the sources in the source files, it is
 possible to declare them in the :file:`setup.py` file::
 
-   from distutils.core import setup
+   from setuptools import setup
    from Cython.Build import cythonize
 
    setup(ext_modules = cythonize(
@@ -553,7 +553,7 @@ recognize the ``language`` option and it needs to be specified as an
 option to an :class:`Extension` that describes your extension and that
 is then handled by ``cythonize()`` as follows::
 
-   from distutils.core import setup, Extension
+   from setuptools import Extension, setup
    from Cython.Build import cythonize
 
    setup(ext_modules = cythonize(Extension(
@@ -568,7 +568,7 @@ often preferable (and overrides any global option).  Starting with
 version 0.17, Cython also allows passing external source files into the
 ``cythonize()`` command this way.  Here is a simplified setup.py file::
 
-   from distutils.core import setup
+   from setuptools import setup
    from Cython.Build import cythonize
 
    setup(
@@ -586,8 +586,8 @@ any source code, to compile it in C++ mode and link it statically against the
 .. note::
 
      When using distutils directives, the paths are relative to the working
-     directory of the distutils run (which is usually the
-     project root where the :file:`setup.py` resides).
+     directory of the setuptools run (which is usually the project root where
+     the :file:`setup.py` resides).
 
 To compile manually (e.g. using ``make``), the ``cython`` command-line
 utility can be used to generate a C++ ``.cpp`` file, and then compile it