first set of checkins from the doc editor

1 files changed, 195 insertions, 14 deletions

diff --git a/numpy/distutils/ccompiler.py b/numpy/distutils/ccompiler.py
index 63f9744f7..3137cc03f 100644
--- a/numpy/distutils/ccompiler.py
+++ b/numpy/distutils/ccompiler.py
@@ -26,6 +26,27 @@ def replace_method(klass, method_name, func):
 
 # Using customized CCompiler.spawn.
 def CCompiler_spawn(self, cmd, display=None):
+    """
+    Execute a command in a sub-process.
+
+    Parameters
+    ----------
+    cmd : str
+        The command to execute.
+    display : str or sequence of str, optional
+        The text to add to the log file kept by `numpy.distutils`.
+        If not given, `display` is equal to `cmd`.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    DistutilsExecError
+        If the command failed, i.e. the exit status was not 0.
+
+    """
     if display is None:
         display = cmd
         if is_sequence(display):
@@ -46,6 +67,28 @@ def CCompiler_spawn(self, cmd, display=None):
 replace_method(CCompiler, 'spawn', CCompiler_spawn)
 
 def CCompiler_object_filenames(self, source_filenames, strip_dir=0, output_dir=''):
+    """
+    Return the name of the object files for the given source files.
+
+    Parameters
+    ----------
+    source_filenames : list of str
+        The list of paths to source files. Paths can be either relative or
+        absolute, this is handled transparently.
+    strip_dir : bool, optional
+        Whether to strip the directory from the returned paths. If True,
+        the file name prepended by `output_dir` is returned. Default is False.
+    output_dir : str, optional
+        If given, this path is prepended to the returned paths to the
+        object files.
+
+    Returns
+    -------
+    obj_names : list of str
+        The list of paths to the object files corresponding to the source
+        files in `source_filenames`.
+
+    """
     if output_dir is None:
         output_dir = ''
     obj_names = []
@@ -74,6 +117,41 @@ replace_method(CCompiler, 'object_filenames', CCompiler_object_filenames)
 def CCompiler_compile(self, sources, output_dir=None, macros=None,
                       include_dirs=None, debug=0, extra_preargs=None,
                       extra_postargs=None, depends=None):
+    """
+    Compile one or more source files.
+
+    Please refer to the Python distutils API reference for more details.
+
+    Parameters
+    ----------
+    sources : list of str
+        A list of filenames
+    output_dir : str, optional
+        Path to the output directory.
+    macros : list of tuples
+        A list of macro definitions.
+    include_dirs : list of str, optional
+        The directories to add to the default include file search path for
+        this compilation only.
+    debug : bool, optional
+        Whether or not to output debug symbols in or alongside the object
+        file(s).
+    extra_preargs, extra_postargs : ?
+        Extra pre- and post-arguments.
+    depends : list of str, optional
+        A list of file names that all targets depend on.
+
+    Returns
+    -------
+    objects : list of str
+        A list of object file names, one per source file `sources`.
+
+    Raises
+    ------
+    CompileError
+        If compilation fails.
+
+    """
     # This method is effective only with Python >=2.3 distutils.
     # Any changes here should be applied also to fcompiler.compile
     # method to support pre Python 2.3 distutils.
@@ -122,7 +200,23 @@ def CCompiler_compile(self, sources, output_dir=None, macros=None,
 replace_method(CCompiler, 'compile', CCompiler_compile)
 
 def CCompiler_customize_cmd(self, cmd, ignore=()):
-    """ Customize compiler using distutils command.
+    """
+    Customize compiler using distutils command.
+
+    Parameters
+    ----------
+    cmd : class instance
+        An instance inheriting from `distutils.cmd.Command`.
+    ignore : sequence of str, optional
+        List of `CCompiler` commands (without ``'set_'``) that should not be
+        altered. Strings that are checked for are:
+        ``('include_dirs', 'define', 'undef', 'libraries', 'library_dirs',
+        'rpath', 'link_objects')``.
+
+    Returns
+    -------
+    None
+
     """
     log.info('customize %s using %s' % (self.__class__.__name__,
                                         cmd.__class__.__name__))
@@ -169,6 +263,22 @@ def _compiler_to_string(compiler):
     return '\n'.join(lines)
 
 def CCompiler_show_customization(self):
+    """
+    Print the compiler customizations to stdout.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    Printing is only done if the distutils log threshold is < 2.
+
+    """
     if 0:
         for attrname in ['include_dirs','define','undef',
                          'libraries','library_dirs',
@@ -190,6 +300,35 @@ def CCompiler_show_customization(self):
 replace_method(CCompiler, 'show_customization', CCompiler_show_customization)
 
 def CCompiler_customize(self, dist, need_cxx=0):
+    """
+    Do any platform-specific customization of a compiler instance.
+
+    This method calls `distutils.sysconfig.customize_compiler` for
+    platform-specific customization, as well as optionally remove a flag
+    to suppress spurious warnings in case C++ code is being compiled.
+
+    Parameters
+    ----------
+    dist : object
+        This parameter is not used for anything.
+    need_cxx : bool, optional
+        Whether or not C++ has to be compiled. If so (True), the
+        ``"-Wstrict-prototypes"`` option is removed to prevent spurious
+        warnings. Default is False.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    All the default options used by distutils can be extracted with::
+
+      from distutils import sysconfig
+      sysconfig.get_config_vars('CC', 'CXX', 'OPT', 'BASECFLAGS',
+                                'CCSHARED', 'LDSHARED', 'SO')
+
+    """
     # See FCompiler.customize for suggested usage.
     log.info('customize %s' % (self.__class__.__name__))
     customize_compiler(self)
@@ -225,18 +364,29 @@ replace_method(CCompiler, 'customize', CCompiler_customize)
 
 def simple_version_match(pat=r'[-.\d]+', ignore='', start=''):
     """
-    Simple matching of version numbers, for use in CCompiler and FCompiler
-    classes.
-
-    :Parameters:
-        pat : regex matching version numbers.
-        ignore : false or regex matching expressions to skip over.
-        start : false or regex matching the start of where to start looking
-                for version numbers.
-
-    :Returns:
-        A function that is appropiate to use as the .version_match
-        attribute of a CCompiler class.
+    Simple matching of version numbers, for use in CCompiler and FCompiler.
+
+    Parameters
+    ----------
+    pat : str, optional
+        A regular expression matching version numbers.
+        Default is ``r'[-.\\d]+'``.
+    ignore : str, optional
+        A regular expression matching patterns to skip.
+        Default is ``''``, in which case nothing is skipped.
+    start : str, optional
+        A regular expression matching the start of where to start looking
+        for version numbers.
+        Default is ``''``, in which case searching is started at the
+        beginning of the version string given to `matcher`.
+
+    Returns
+    -------
+    matcher : callable
+        A function that is appropriate to use as the ``.version_match``
+        attribute of a `CCompiler` class. `matcher` takes a single parameter,
+        a version string.
+
     """
     def matcher(self, version_string):
         pos = 0
@@ -257,7 +407,25 @@ def simple_version_match(pat=r'[-.\d]+', ignore='', start=''):
     return matcher
 
 def CCompiler_get_version(self, force=False, ok_status=[0]):
-    """Compiler version. Returns None if compiler is not available."""
+    """
+    Return compiler version, or None if compiler is not available.
+
+    Parameters
+    ----------
+    force : bool, optional
+        If True, force a new determination of the version, even if the
+        compiler already has a version attribute. Default is False.
+    ok_status : list of int, optional
+        The list of status values returned by the version look-up process
+        for which a version string is returned. If the status value is not
+        in `ok_status`, None is returned. Default is ``[0]``.
+
+    Returns
+    -------
+    version : str or None
+        Version string, in the format of `distutils.version.LooseVersion`.
+
+    """
     if not force and hasattr(self,'version'):
         return self.version
     self.find_executables()
@@ -294,6 +462,19 @@ def CCompiler_get_version(self, force=False, ok_status=[0]):
 replace_method(CCompiler, 'get_version', CCompiler_get_version)
 
 def CCompiler_cxx_compiler(self):
+    """
+    Return the C++ compiler.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    cxx : class instance
+        The C++ compiler, as a `CCompiler` instance.
+
+    """
     if self.compiler_type=='msvc': return self
     cxx = copy(self)
     cxx.compiler_so = [cxx.compiler_cxx[0]] + cxx.compiler_so[1:]