[Docs] Move Cython remarks to the new ext_modules page

This helps to consolidate all the information about extensions in a
single place and make it easier for users to find the correct
guidance.

3 files changed, 55 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 db0f1a5f..b4f31985 100644
--- a/docs/userguide/distribution.rst
+++ b/docs/userguide/distribution.rst
@@ -117,44 +117,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..69b0a286 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,47 @@ 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
+============================================
+
+``setuptools`` will detect at build time whether :pypi:`Cython` is installed or not.
+If Cython is not found ``setuptools`` will ignore ``.pyx`` files.
+
+To ensure Cython is available, include Cython in the :ref:`build-requires` section
+of 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.
+Please checkout our docs on :ref:`controlling files in the distribution` for
+more information.
 
 ----
 
-API Reference
--------------
+Extension API Reference
+=======================
 
 .. autoclass:: setuptools.Extension