Merge pull request #2295 from gabrieldemarmiesse/duplicate_cythonize

Moved the cythonize description from the docs to the docstring.

2 files changed, 61 insertions, 93 deletions

diff --git a/Cython/Build/Dependencies.py b/Cython/Build/Dependencies.py
index 9e6488e54..ca1ec5a08 100644
--- a/Cython/Build/Dependencies.py
+++ b/Cython/Build/Dependencies.py
@@ -870,27 +870,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
-    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
-    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.
-
-    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 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`.
     """
     if exclude is None:
         exclude = []
diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst
index 95afc6051..ff6a755d8 100644
--- a/docs/src/reference/compilation.rst
+++ b/docs/src/reference/compilation.rst
@@ -250,78 +250,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
 ----------------------------