Merge pull request #2179 from gabrieldemarmiesse/pyximport

Added argument list for pyximport.

docs/conf.py

@@ -43,7 +43,8 @@ extensions = [
     'cython_highlighting',
     'sphinx.ext.pngmath',
     'sphinx.ext.todo',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc'
     ]
 
 try: import rst2pdf

docs/src/quickstart/build.rst

@@ -18,7 +18,7 @@ one may want to read more about
 There are several ways to build Cython code:
 
  - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way.
- - Use ``pyximport``, importing Cython ``.pyx`` files as if they
+ - Use :ref:`Pyximport<pyximport>`, importing Cython ``.pyx`` files as if they
    were ``.py`` files (using distutils to compile and build in the background).
    This method is easier than writing a ``setup.py``, but is not very flexible.
    So you'll need to write a ``setup.py`` if, for example, you need certain compilations options.

docs/src/tutorial/cython_tutorial.rst

@@ -77,7 +77,7 @@ It is shipped and installed with Cython and can be used like this::
     >>> import helloworld
     Hello World
 
-Since Cython 0.11, the :mod:`pyximport` module also has experimental
+Since Cython 0.11, the :ref:`Pyximport<pyximport>` module also has experimental
 compilation support for normal Python modules.  This allows you to
 automatically run Cython on every .pyx and .py module that Python
 imports, including the standard library and installed packages.
@@ -87,7 +87,7 @@ modules instead.  The .py import mechanism is installed like this::
 
     >>> pyximport.install(pyimport=True)
 
-Note that it is not recommended to let :mod:`pyximport` build code
+Note that it is not recommended to let :ref:`Pyximport<pyximport>` build code
 on end user side as it hooks into their import system.  The best way
 to cater for end users is to provide pre-built binary packages in the
 `wheel <https://wheel.readthedocs.io/>`_ packaging format.

docs/src/tutorial/profiling_tutorial.rst

@@ -216,7 +216,7 @@ meaningful output from the cProfile module. The rest of the code is mostly
 unchanged, I only typed some variables which will likely speed things up a bit.
 
 We also need to modify our profiling script to import the Cython module directly.
-Here is the complete version adding the import of the pyximport module::
+Here is the complete version adding the import of the :ref:`Pyximport<pyximport>` module::
 
    #!/usr/bin/env python
    # encoding: utf-8

docs/src/userguide/source_files_and_compilation.rst

@@ -107,6 +107,14 @@ on end user side as it hooks into their import system.  The best way
 to cater for end users is to provide pre-built binary packages in the
 `wheel <https://wheel.readthedocs.io/>`_ packaging format.
 
+Arguments
+---------
+
+The function ``pyximport.install()`` can take several arguments to
+influence the compilation of Cython or Python files.
+
+.. autofunction:: pyximport.install
+
 Dependency Handling
 --------------------
 

pyximport/pyximport.py

@@ -485,49 +485,53 @@ def install(pyximport=True, pyimport=False, build_dir=None, build_in_temp=True,
             setup_args=None, reload_support=False,
             load_py_module_on_import_failure=False, inplace=False,
             language_level=None):
-    """Main entry point. Call this to install the .pyx import hook in
+    """ Main entry point for pyxinstall.
+
+    Call this to install the ``.pyx`` import hook in
     your meta-path for a single Python process.  If you want it to be
-    installed whenever you use Python, add it to your sitecustomize
+    installed whenever you use Python, add it to your ``sitecustomize``
     (as described above).
 
-    You can pass ``pyimport=True`` to also install the .py import hook
-    in your meta-path.  Note, however, that it is highly experimental,
-    will not work for most .py files, and will therefore only slow
-    down your imports.  Use at your own risk.
-
-    By default, compiled modules will end up in a ``.pyxbld``
-    directory in the user's home directory.  Passing a different path
-    as ``build_dir`` will override this.
-
-    ``build_in_temp=False`` will produce the C files locally. Working
-    with complex dependencies and debugging becomes more easy. This
-    can principally interfere with existing files of the same name.
-    build_in_temp can be overridden by <modulename>.pyxbld/make_setup_args()
-    by a dict item of 'build_in_temp'
-
-    ``setup_args``: dict of arguments for Distribution - see
-    distutils.core.setup() . They are extended/overridden by those of
-    <modulename>.pyxbld/make_setup_args()
-
-    ``reload_support``:  Enables support for dynamic
-    reload(<pyxmodulename>), e.g. after a change in the Cython code.
-    Additional files <so_path>.reloadNN may arise on that account, when
-    the previously loaded module file cannot be overwritten.
-
-    ``load_py_module_on_import_failure``: If the compilation of a .py
-    file succeeds, but the subsequent import fails for some reason,
-    retry the import with the normal .py module instead of the
-    compiled module.  Note that this may lead to unpredictable results
-    for modules that change the system state during their import, as
-    the second import will rerun these modifications in whatever state
-    the system was left after the import of the compiled module
-    failed.
-
-    ``inplace``: Install the compiled module next to the source file.
-
-    ``language_level``: The source language level to use: 2 or 3.
-    The default is to use the language level of the current Python
-    runtime for .py files and Py2 for .pyx files.
+    :param pyximport: If set to False, does not try to import ``.pyx`` files.
+
+    :param pyimport: You can pass ``pyimport=True`` to also
+        install the ``.py`` import hook
+        in your meta-path.  Note, however, that it is highly experimental,
+        will not work for most ``.py`` files, and will therefore only slow
+        down your imports.  Use at your own risk.
+
+    :param build_dir: By default, compiled modules will end up in a ``.pyxbld``
+        directory in the user's home directory.  Passing a different path
+        as ``build_dir`` will override this.
+
+    :param build_in_temp: If ``False``, will produce the C files locally. Working
+        with complex dependencies and debugging becomes more easy. This
+        can principally interfere with existing files of the same name.
+
+    :param setup_args: Dict of arguments for Distribution.
+        See ``distutils.core.setup()``.
+
+    :param reload_support: Enables support for dynamic
+        ``reload(my_module)``, e.g. after a change in the Cython code.
+        Additional files ``<so_path>.reloadNN`` may arise on that account, when
+        the previously loaded module file cannot be overwritten.
+
+    :param load_py_module_on_import_failure: If the compilation of a ``.py``
+        file succeeds, but the subsequent import fails for some reason,
+        retry the import with the normal ``.py`` module instead of the
+        compiled module.  Note that this may lead to unpredictable results
+        for modules that change the system state during their import, as
+        the second import will rerun these modifications in whatever state
+        the system was left after the import of the compiled module
+        failed.
+
+    :param inplace: Install the compiled module
+        (``.so`` for Linux and Mac / ``.pyd`` for Windows)
+        next to the source file.
+
+    :param language_level: The source language level to use: 2 or 3.
+        The default is to use the language level of the current Python
+        runtime for .py files and Py2 for ``.pyx`` files.
     """
     if setup_args is None:
         setup_args = {}