Simplify text about Cython

1 files changed, 21 insertions, 23 deletions

diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst
index 69b0a286..0467f4ec 100644
--- a/docs/userguide/ext_modules.rst
+++ b/docs/userguide/ext_modules.rst
@@ -105,36 +105,33 @@ The linker searches for libraries in the following order:
 Distributing Extensions compiled with Cython
 ============================================
 
-``setuptools`` will detect at build time whether :pypi:`Cython` is installed or not.
-If Cython is not found ``setuptools`` will ignore ``.pyx`` files.
+When your :pypi:`Cython` extension modules *are declared using the*
+:class:`setuptools.Extension` *class*, ``setuptools`` will detect at build time
+whether Cython is installed or not.
 
-To ensure Cython is available, include Cython in the :ref:`build-requires` section
-of your ``pyproject.toml``:
+If Cython is present, then ``setuptools`` will use it to build the ``.pyx`` files.
+Otherwise, ``setuptools`` will try to find and compile the equivalent ``.c`` files
+(instead of ``.pyx``). These files can be generated using the
+`cython command line tool`_.
+
+You can ensure that Cython is always automatically installed into the build
+environment by including it as a :ref:`build dependency <build-requires>` in
+your ``pyproject.toml``:
 
 .. code-block:: toml
 
     [build-system]
     requires = [..., "cython"]
 
-For :pypi:`pip` 10 or later, that declaration is sufficient to include Cython
-in the build.
-
-As long as Cython is present in the build environment **and** extensions
-are defined using ``setuptools.Extension``, ``setuptools`` includes
-transparent support for building Cython extensions.
-
-If you follow these rules, you can safely list ``.pyx`` files as the source
-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 Cython, as well as your original ``.pyx`` files.  This means
-that you will probably want to include current ``.c`` files in your :wiki:`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 Cython
-installed, and that your source releases will be similarly usable with or
-without Cython.
+Alternatively, you can include the ``.c`` code that is pre-compiled by Cython
+into your source distribution, alongside the original ``.pyx`` files (this
+might save a few seconds when building from an ``sdist``).
+To improve version compatibility, you probably also want to include current
+``.c`` files in your :wiki:`revision control system`, and rebuild them whenever
+you check changes in for the ``.pyx`` source files.
+This will ensure that people tracking your project will be able to build it
+without installing Cython, and that there will be no variation due to small
+differences in the generate C files.
 Please checkout our docs on :ref:`controlling files in the distribution` for
 more information.
 
@@ -150,3 +147,4 @@ Extension API Reference
 .. _Cython: https://cython.readthedocs.io/en/stable/index.html
 .. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html
 .. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html>
+.. _cython command line tool: https://cython.readthedocs.io/en/stable/src/userguide/source_files_and_compilation.html