[Docs] Move Cython remarks to the new ext_modules page (#3373)

3 files changed, 53 insertions, 55 deletions

diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index c7f1e059..a35d7bfc 100644
--- a/docs/userguide/dependency_management.rst
+++ b/docs/userguide/dependency_management.rst
@@ -15,6 +15,8 @@ dependency.
    :pep:`direct URLs <440#direct-references>`.
 
 
+.. _build-requires:
+
 Build system requirement
 ========================
 
@@ -24,7 +26,7 @@ do the packaging (in our case, ``setuptools`` of course).
 This needs to be specified in your ``pyproject.toml`` file
 (if you have forgot what this is, go to :doc:`/userguide/quickstart` or :doc:`/build_meta`):
 
-.. code-block:: ini
+.. code-block:: toml
 
     [build-system]
     requires = ["setuptools"]
diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst
index d2d0ea88..543e6296 100644
--- a/docs/userguide/distribution.rst
+++ b/docs/userguide/distribution.rst
@@ -86,44 +86,6 @@ Or of course you can create more elaborate aliases that do all of the above.
 See the sections below on the :ref:`egg_info <egg_info>` and
 :ref:`alias <alias>` commands for more ideas.
 
-Distributing Extensions compiled with Cython
---------------------------------------------
-
-``setuptools`` will detect at build time whether Cython is installed or not.
-If Cython is not found ``setuptools`` will ignore pyx files.
-
-To ensure Cython is available, include Cython in the build-requires section
-of your pyproject.toml::
-
-    [build-system]
-    requires=[..., "cython"]
-
-Built with pip 10 or later, that declaration is sufficient to include Cython
-in the build. For broader compatibility, declare the dependency in your
-setup-requires of setup.cfg::
-
-    [options]
-    setup_requires =
-        ...
-        cython
-
-As long as Cython is present in the build environment, ``setuptools`` includes
-transparent support for building Cython extensions, as
-long as extensions are defined using ``setuptools.Extension``.
-
-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 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.
-
 
 .. _Specifying Your Project's Version:
 
diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst
index 213e13c0..0467f4ec 100644
--- a/docs/userguide/ext_modules.rst
+++ b/docs/userguide/ext_modules.rst
@@ -45,11 +45,23 @@ To instruct setuptools to compile the ``foo.c`` file into the extension module
    )
 
 .. seealso::
-    You can find more information on the `Python docs about C/C++ extensions`_.
-    Alternatively, you might also be interested in learn about `Cython`_.
+   You can find more information on the `Python docs about C/C++ extensions`_.
+   Alternatively, you might also be interested in learn about `Cython`_.
 
-    If you plan to distribute a package that uses extensions across multiple
-    platforms, :pypi:`cibuildwheel` can also be helpful.
+   If you plan to distribute a package that uses extensions across multiple
+   platforms, :pypi:`cibuildwheel` can also be helpful.
+
+.. important::
+   All files used to compile your extension need to be available on the system
+   when building the package, so please make sure to include some documentation
+   on how developers interested in building your package from source
+   can obtain operating system level dependencies
+   (e.g. compilers and external binary libraries/artifacts).
+
+   You will also need to make sure that all auxiliary files that are contained
+   inside your :term:`project` (e.g. C headers authored by you or your team)
+   are configured to be included in your :term:`sdist <Source Distribution (or "sdist")>`.
+   Please have a look on our section on :ref:`Controlling files in the distribution`.
 
 
 Compiler and linker options
@@ -89,23 +101,44 @@ The linker searches for libraries in the following order:
 * first, in directories given by ``-L`` options (in left-to-right order),
 * then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order).
 
-.. important::
-   All files used to compile your extension need to be available on the system
-   when building the package, so please make sure to include some documentation
-   on how developers interested in building your package from source
-   can obtain operating system level dependencies
-   (e.g. compilers and external binary libraries/artifacts).
 
-   You will also need to make sure that all auxiliary files that are contained
-   inside your :term:`project` (e.g. C headers authored by you or your team)
-   are configured to be included in your :term:`sdist <Source Distribution (or "sdist")>`.
-   Please have a look on our section on :ref:`Controlling files in the distribution`.
+Distributing Extensions compiled with Cython
+============================================
+
+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.
+
+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"]
+
+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.
 
 ----
 
-API Reference
--------------
+Extension API Reference
+=======================
 
 .. autoclass:: setuptools.Extension
 
@@ -114,3 +147,4 @@ 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