Document building Cython projects instead of Pyrex

Refs #1395

changelog.d/1395.doc.rst

+Document building Cython projects instead of Pyrex

docs/setuptools.txt

@@ -41,9 +41,9 @@ 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
@@ -1651,29 +1651,34 @@ 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`` 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.
+``setuptools`` will detect at build time whether Cython is installed or not.
+If Cython is not found ``setputools`` will ignore pyx files. In case it's
+available you are supposed it will work with just a couple of adjustments.
+``setuptools`` includes transparent support for building Cython extensions, as
+long as you define your extensions using ``setuptools.Extension``.
+Then you should use Cython own ``build_ext`` in ``cmdclass``, e.g.::
+
+   from Cython.Distutils import build_ext
+
+   setup(...
+         cmdclass={"build_ext": build_ext}
+         ...)
 
 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.
 
 
 -----------------