Used autodocs because it makes more sense.

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/userguide/source_files_and_compilation.rst

@@ -113,44 +113,7 @@ Arguments
 The function ``pyximport.install()`` can take several arguments to
 influence the compilation of Cython or Python files.
 
-.. function:: pyximport.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)
-
-    :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.
+.. 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
+    :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
+        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``
+    :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.
 
-    ``build_in_temp=False`` will produce the C files locally. Working
+    :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.
-    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()
+    :param setup_args: Dict of arguments for Distribution.
+        See ``distutils.core.setup()``.
 
-    ``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
+    :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.
 
-    ``load_py_module_on_import_failure``: If the compilation of a .py
+    :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
+        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.
+    :param inplace: Install the compiled module
+        (``.so`` for Linux and Mac / ``.pyd`` for Windows)
+        next to the source file.
 
-    ``language_level``: The source language level to use: 2 or 3.
+    :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.
+        runtime for .py files and Py2 for ``.pyx`` files.
     """
     if setup_args is None:
         setup_args = {}