Removed the description of cythonize in the docs and instead, moved it to the...

Removed the description of cythonize in the docs and instead, moved it to the docstring and used autodocs to pull it in the docs.

Cython/Build/Dependencies.py

@@ -871,27 +871,65 @@ def cythonize(module_list, exclude=None, nthreads=0, aliases=None, quiet=False,
     Compile a set of source modules into C/C++ files and return a list of distutils
     Extension objects for them.
 
-    As module list, pass either a glob pattern, a list of glob patterns or a list of
-    Extension objects.  The latter allows you to configure the extensions separately
+    :param module_list: As module list, pass either a glob pattern, a list of glob
+                        patterns or a list of Extension objects.  The latter
+                        allows you to configure the extensions separately
                         through the normal distutils options.
-
-    When using glob patterns, you can exclude certain module names explicitly
-    by passing them into the 'exclude' option.
-
-    To globally enable C++ mode, you can pass language='c++'.  Otherwise, this
+                        You can also pass Extension objects that have
+                        glob patterns as their sources. Then, cythonize
+                        will resolve the pattern and create a
+                        copy of the Extension for every matching file.
+
+    :param exclude: When passing glob patterns as ``module_list``, you can exclude certain
+                    module names explicitly by passing them into the ``exclude`` option.
+
+    :param nthreads: The number of concurrent builds for parallel compilation
+                     (requires the ``multiprocessing`` module).
+
+    :param aliases: If you want to use compiler directives like ``# distutils: ...`` but
+                    can only know at compile time (when running the ``setup.py``) which values
+                    to use, you can use aliases and pass a dictionary mapping those aliases
+                    to Python strings when calling :func:`cythonize`. As an example, say you
+                    want to use the compiler
+                    directive ``# distutils: include_dirs = ../static_libs/include/``
+                    but this path isn't always fixed and you want to find it when running
+                    the ``setup.py``. You can then do ``# distutils: include_dirs = MY_HEADERS``,
+                    find the value of ``MY_HEADERS`` in the ``setup.py``, put it in a python
+                    variable called ``foo`` as a string, and then call
+                    ``cythonize(..., aliases={'MY_HEADERS': foo})``.
+
+    :param quiet: If True, Cython won't print error and warning messages during the compilation.
+
+    :param force: Forces the recompilation of the Cython modules, even if the timestamps
+                  don't indicate that a recompilation is necessary.
+
+    :param language: To globally enable C++ mode, you can pass ``language='c++'``. Otherwise, this
                      will be determined at a per-file level based on compiler directives.  This
                      affects only modules found based on file names.  Extension instances passed
-    into cythonize() will not be changed.
-
-    For parallel compilation, set the 'nthreads' option to the number of
-    concurrent builds.
+                     into :func:`cythonize` will not be changed. It is recommended to rather
+                     use the compiler directive ``# distutils: language = c++`` than this option.
 
-    For a broad 'try to compile' mode that ignores compilation failures and
-    simply excludes the failed extensions, pass 'exclude_failures=True'. Note
-    that this only really makes sense for compiling .py files which can also
+    :param exclude_failures: For a broad 'try to compile' mode that ignores compilation
+                             failures and simply excludes the failed extensions,
+                             pass ``exclude_failures=True``. Note that this only
+                             really makes sense for compiling ``.py`` files which can also
                              be used without compilation.
 
-    Additional compilation options can be passed as keyword arguments.
+    :param annotate: If ``True``, will produce a HTML file for each of the ``.pyx`` or ``.py``
+                     files compiled. The HTML file gives an indication
+                     of how much Python interaction there is in
+                     each of the source code lines, compared to plain C code.
+                     It also allows you to see the C/C++ code
+                     generated for each line of Cython code. This report is invaluable when
+                     optimizing a function for speed,
+                     and for determining when to :ref:`release the GIL <nogil>`:
+                     in general, a ``nogil`` block may contain only "white" code.
+                     See examples in :ref:`determining_where_to_add_types` or
+                     :ref:`primes`.
+
+    :param compiler_directives: Allow to set compiler directives in the ``setup.py`` like this:
+                                ``compiler_directives={'embedsignature': True}``.
+                                See :ref:`compiler-directives`.
     """
     if exclude is None:
         exclude = []

docs/src/reference/compilation.rst

@@ -243,78 +243,8 @@ Cythonize arguments
 The function :func:`cythonize` can take extra arguments which will allow you to
 customize your build.
 
-.. py:function:: cythonize(module_list, \
-                           exclude=None, \
-                           nthreads=0, \
-                           aliases=None, \
-                           quiet=False, \
-                           force=False, \
-                           language=None, \
-                           exclude_failures=False, \
-                           **options)
-
-    Compile a set of source modules into C/C++ files and return a list of distutils
-    Extension objects for them.
-
-    :param module_list: As module list, pass either a glob pattern, a list of glob
-                        patterns or a list of Extension objects.  The latter
-                        allows you to configure the extensions separately
-                        through the normal distutils options.
-                        You can also pass Extension objects that have
-                        glob patterns as their sources. Then, cythonize
-                        will resolve the pattern and create a
-                        copy of the Extension for every matching file.
-
-    :param exclude: When passing glob patterns as ``module_list``, you can exclude certain
-                    module names explicitly by passing them into the ``exclude`` option.
-
-    :param nthreads: The number of concurrent builds for parallel compilation
-                     (requires the ``multiprocessing`` module).
-
-    :param aliases: If you want to use compiler directives like ``# distutils: ...`` but
-                    can only know at compile time (when running the ``setup.py``) which values
-                    to use, you can use aliases and pass a dictionary mapping those aliases
-                    to Python strings when calling :func:`cythonize`. As an example, say you
-                    want to use the compiler
-                    directive ``# distutils: include_dirs = ../static_libs/include/``
-                    but this path isn't always fixed and you want to find it when running
-                    the ``setup.py``. You can then do ``# distutils: include_dirs = MY_HEADERS``,
-                    find the value of ``MY_HEADERS`` in the ``setup.py``, put it in a python
-                    variable called ``foo`` as a string, and then call
-                    ``cythonize(..., aliases={'MY_HEADERS': foo})``.
-
-    :param quiet: If True, Cython won't print error and warning messages during the compilation.
-
-    :param force: Forces the recompilation of the Cython modules, even if the timestamps
-                  don't indicate that a recompilation is necessary.
-
-    :param language: To globally enable C++ mode, you can pass ``language='c++'``. Otherwise, this
-                     will be determined at a per-file level based on compiler directives.  This
-                     affects only modules found based on file names.  Extension instances passed
-                     into :func:`cythonize` will not be changed. It is recommended to rather
-                     use the compiler directive ``# distutils: language = c++`` than this option.
-
-    :param exclude_failures: For a broad 'try to compile' mode that ignores compilation
-                             failures and simply excludes the failed extensions,
-                             pass ``exclude_failures=True``. Note that this only
-                             really makes sense for compiling ``.py`` files which can also
-                             be used without compilation.
-
-    :param annotate: If ``True``, will produce a HTML file for each of the ``.pyx`` or ``.py``
-                     files compiled. The HTML file gives an indication
-                     of how much Python interaction there is in
-                     each of the source code lines, compared to plain C code.
-                     It also allows you to see the C/C++ code
-                     generated for each line of Cython code. This report is invaluable when
-                     optimizing a function for speed,
-                     and for determining when to :ref:`release the GIL <nogil>`:
-                     in general, a ``nogil`` block may contain only "white" code.
-                     See examples in :ref:`determining_where_to_add_types` or
-                     :ref:`primes`.
-
-    :param compiler_directives: Allow to set compiler directives in the ``setup.py`` like this:
-                                ``compiler_directives={'embedsignature': True}``.
-                                See :ref:`compiler-directives`.
+.. autofunction:: Cython.Build.cythonize
+
 
 Distributing Cython modules
 ----------------------------