sphinx build: move docstring changes to own PR [ci skip]

Split this patchset so it contains only the Sphinx-build configuration
itself, and not any docstring changes suggested by running Sphinx.

Signed-off-by: Mats Wichmann <[email protected]>

Author: mwichmann

SCons/Environment.py

@@ -1502,16 +1502,11 @@ def Detect(self, progs):
     def Dictionary(self, *args):
         """Return construction variables from an environment.
 
-        Args:
-          args: (optional) variable names to look up
-
-        Returns:
-          if args omitted, the dictionary of all consvars.
-          If one arg, the corresponding value is returned.
-          If more than one arg, a list of values is returned.
-
-        Raises:
-          KeyError: if any of args is not in the construction env.
+        :param *args: (optional) variable names to look up
+        :returns: if args omitted, the dictionary of all constr. vars.
+            If one arg, the corresponding value is returned.
+            If more than one arg, a list of values is returned.
+        :raises KeyError: if any of *args is not in the construction env.
 
         """
         if not args:
@@ -1525,13 +1520,12 @@ def Dictionary(self, *args):
     def Dump(self, key=None, format='pretty'):
         """ Serialize the construction variables to a string.
 
-        Args:
-          key: if None, format the whole dict of variables.
-            Else format just the value for key (Default value = None)
-          format: specify the format of the variables to be serialized:
+        :param key: if None, format the whole dict of variables.
+            Else look up and format just the value for key.
+            
+        :param format: specify the format of the variables to be serialized:
             - pretty: pretty-printed string.
             - json: JSON-formatted string.
-            (Default value = None)
 
         """
         if key:
@@ -1562,15 +1556,12 @@ def non_serializable(obj):
 
 
     def FindIxes(self, paths, prefix, suffix):
-        """Search a list of paths for something that matches the prefix and suffix.
-
-        Args:
-          paths: the list of paths or nodes.
-          prefix: construction variable for the prefix.
-          suffix: construction variable for the suffix.
-
-        Returns: the matched path or None
+        """
+        Search a list of paths for something that matches the prefix and suffix.
 
+        paths - the list of paths or nodes.
+        prefix - construction variable for the prefix.
+        suffix - construction variable for the suffix.
         """
 
         suffix = self.subst('$'+suffix)
@@ -2026,7 +2017,7 @@ def Command(self, target, source, action, **kw):
             pass
         else:
             del kw['target_factory']
-
+            
         bld = SCons.Builder.Builder(**bkw)
         return bld(self, target, source, **kw)
 

SCons/Errors.py

@@ -35,11 +35,13 @@
 
 
 class BuildError(Exception):
-    """SCons Errors that can occur while building.
+    """ Errors occurring while building.
 
-    BuildError has the following attributes:
+    BuildError have the following attributes:
+    =========================================
 
     Information about the cause of the build error:
+    -----------------------------------------------
 
     errstr : a description of the error message
 
@@ -69,6 +71,7 @@ class BuildError(Exception):
 
 
     Information about the cause of the location of the error:
+    ---------------------------------------------------------
 
     node : the error occured while building this target node(s)
 

SCons/Platform/__init__.py

@@ -56,10 +56,10 @@
 
 
 def platform_default():
-    r"""Return the platform string for our execution environment.
+    """Return the platform string for our execution environment.
 
     The returned value should map to one of the SCons/Platform/*.py
-    files.  Since scons is architecture independent, though, we don't
+    files.  Since we're architecture independent, though, we don't
     care about the machine architecture.
     """
     osname = os.name
@@ -131,30 +131,26 @@ def __str__(self):
 
 
 class TempFileMunge:
-    """A callable class to enable temp files for long command lines.
-
-    You can set an Environment variable to this,
+    """A callable class.  You can set an Environment variable to this,
     then call it with a string argument, then it will perform temporary
     file substitution on it.  This is used to circumvent the long command
-    line limitation.  Example::
+    line limitation.
 
+    Example usage:
         env["TEMPFILE"] = TempFileMunge
         env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES','$LINKCOMSTR')}"
 
     By default, the name of the temporary file used begins with a
     prefix of '@'.  This may be configured for other tool chains by
-    setting '$TEMPFILEPREFIX'. Example::
-
+    setting '$TEMPFILEPREFIX':
         env["TEMPFILEPREFIX"] = '-@'        # diab compiler
         env["TEMPFILEPREFIX"] = '-via'      # arm tool chain
         env["TEMPFILEPREFIX"] = ''          # (the empty string) PC Lint
 
     You can configure the extension of the temporary file through the
     TEMPFILESUFFIX variable, which defaults to '.lnk' (see comments
-    in the code below). Example::
-
+    in the code below):
         env["TEMPFILESUFFIX"] = '.lnt'   # PC Lint
-
     """
     def __init__(self, cmd, cmdstr = None):
         self.cmd = cmd

SCons/Script/SConsOptions.py

@@ -346,17 +346,15 @@ def reparse_local_options(self):
         Else, this would lead to problems in add_local_option()
         below. When called from there, we try to reparse the
         command-line arguments that
-
-        1. haven't been processed so far (self.largs), but
-        2. are possibly not added to the list of options yet.
+          1. haven't been processed so far (self.largs), but
+          2. are possibly not added to the list of options yet.
 
         So, when we only have a value for "--myargument" yet,
         a command-line argument of "--myarg=test" would set it.
         Responsible for this behaviour is the method
         _match_long_opt(), which allows for partial matches of
         the option name, as long as the common prefix appears to
         be unique.
-
         This would lead to further confusion, because we might want
         to add another option "--myarg" later on (see issue #2929).
 

SCons/Tool/dmd.py

@@ -10,33 +10,22 @@
 2010-02-07 onwards
 
 Compiler variables:
-
-  DC
-    The name of the D compiler to use.  Defaults to dmd or gdmd, whichever is found.
-  DPATH
-    List of paths to search for import modules.
-  DVERSIONS
-    List of version tags to enable when compiling.
-  DDEBUG
-    List of debug tags to enable when compiling.
+    DC - The name of the D compiler to use.  Defaults to dmd or gdmd,
+        whichever is found.
+    DPATH - List of paths to search for import modules.
+    DVERSIONS - List of version tags to enable when compiling.
+    DDEBUG - List of debug tags to enable when compiling.
 
 Linker related variables:
-
-  LIBS
-    List of library files to link in.
-  DLINK
-    Name of the linker to use.  Defaults to dmd or gdmd, whichever is found.
-  DLINKFLAGS
-    List of linker flags.
+    LIBS - List of library files to link in.
+    DLINK - Name of the linker to use.  Defaults to dmd or gdmd,
+        whichever is found.
+    DLINKFLAGS - List of linker flags.
 
 Lib tool variables:
-
-  DLIB
-    Name of the lib tool to use.  Defaults to lib.
-  DLIBFLAGS
-    List of flags to pass to the lib tool.
-  LIBS
-    Same as for the linker. (libraries to pull into the .lib)
+    DLIB - Name of the lib tool to use.  Defaults to lib.
+    DLIBFLAGS - List of flags to pass to the lib tool.
+    LIBS - Same as for the linker. (libraries to pull into the .lib)
 """
 
 #

SCons/Tool/intelc.py

@@ -387,13 +387,13 @@ def find_in_2016style_dir(version):
 def generate(env, version=None, abi=None, topdir=None, verbose=0):
     r"""Add Builders and construction variables for Intel C/C++ compiler
     to an Environment.
-
-    :param string version: compiler version to use, like "80"
-    :param string abi: 'win32' or whatever Itanium version wants
-    :param string topdir: directory containing compiler tree, e.g.
-      "c:\\Program Files\\Intel\\Compiler70".
-      If `topdir` is used, `version` and `abi` are ignored.
-    :param int verbose: if >0, prints compiler version used.
+    args:
+      version: (string) compiler version to use, like "80"
+      abi:     (string) 'win32' or whatever Itanium version wants
+      topdir:  (string) compiler top dir, like
+                         "c:\Program Files\Intel\Compiler70"
+                        If topdir is used, version and abi are ignored.
+      verbose: (int)    if >0, prints compiler version used.
     """
     if not (is_mac or is_linux or is_windows):
         # can't handle this platform

SCons/Tool/packaging/rpm.py

@@ -302,23 +302,21 @@ def build_specfile_filesection(spec, files):
     return str
 
 class SimpleTagCompiler:
-    """ Compile RPM tags by doing simple string substitution.
+    """ This class is a simple string substition utility:
+    the replacement specfication is stored in the tagset dictionary, something
+    like:
+     { "abc"  : "cdef %s ",
+       "abc_" : "cdef %s %s" }
 
-    The replacement specfication is stored in the *tagset* dictionary,
-    something like:
-
-      {"abc" : "cdef %s ", "abc_": "cdef %s %s"}
-
-    The :func:`compile` function gets a value dictionary, which may look like:
-
-      {"abc": "ghij", "abc_gh": "ij"}
+    the compile function gets a value dictionary, which may look like:
+    { "abc"    : "ghij",
+      "abc_gh" : "ij" }
 
     The resulting string will be:
-
-      "cdef ghij cdef gh ij"
+     "cdef ghij cdef gh ij"
     """
     def __init__(self, tagset, mandatory=1):
-        self.tagset = tagset
+        self.tagset    = tagset
         self.mandatory = mandatory
 
     def compile(self, values):

SCons/Util.py

@@ -1611,18 +1611,16 @@ def cmp(a, b):
 
 
 def get_env_bool(env, name, default=False):
-    """Convert a construction variable to bool.
-
-    If the value of *name* in *env* is 'true', 'yes', 'y', 'on' (case
-    insensitive) or anything convertible to int that yields non-zero then
-    return True; if 'false', 'no', 'n', 'off' (case insensitive)
-    or a number that converts to integer zero return False.
-    Otherwise, return *default*.
-
-    :param env: construction environment, or any dict-like object
-    :param name: name of the variable
-    :param default: value to return if name not in env or cannot be converted (default: False)
-    :rtype: bool
+    """Get a value of env[name] converted to boolean. The value of env[name] is
+    interpreted as follows: 'true', 'yes', 'y', 'on' (case insensitive) and
+    anything convertible to int that yields non-zero integer are True values;
+    '0', 'false', 'no', 'n' and 'off' (case insensitive) are False values. For
+    all other cases, default value is returned.
+
+    :Parameters:
+        - `env`     - dict or dict-like object, a convainer with variables
+        - `name`    - name of the variable in env to be returned
+        - `default` - returned when env[name] does not exist or can't be converted to bool
     """
     try:
         var = env[name]
@@ -1640,10 +1638,7 @@ def get_env_bool(env, name, default=False):
 
 
 def get_os_env_bool(name, default=False):
-    """Convert an environment variable to bool.
-
-    Conversion is the same as for :func:`get_env_bool`.
-    """
+    """Same as get_env_bool(os.environ, name, default)."""
     return get_env_bool(os.environ, name, default)
 
 # Local Variables:

SCons/Variables/__init__.py

@@ -49,22 +49,16 @@ class Variables:
     Holds all the options, updates the environment with the variables,
     and renders the help text.
     """
-    instance = None
-
-    def __init__(self, files=None, args=None, is_global=True):
-        """Create Variables instance.
-
-        If is_global is True, this is a singleton, create only once.
-
-        Args:
-          files: [optional] List of option configuration files to load
-            (backward compatibility). If a single string is passed it is
-            automatically placed in a file list (Default value = None)
-          args - dictionary to override values set from files.
-            (Default value = None)
-          is_global - global instance? (Default value = True)
+    instance=None
 
+    def __init__(self, files=None, args=None, is_global=1):
+        """
+        files - [optional] List of option configuration files to load
+            (backward compatibility) If a single string is passed it is
+            automatically placed in a file list
+        args - dictionary to override values set from files.
         """
+
         if args is None:
             args = {}
         self.options = []
@@ -118,19 +112,18 @@ def keys(self):
         return [o.key for o in self.options]
 
     def Add(self, key, help="", default=None, validator=None, converter=None, **kw):
-        """Add an option.
-
-        Args:
-          key: the name of the variable, or a list or tuple of arguments
-          help: optional help text for the options (Default value = "")
-          default: optional default value for option (Default value = None)
-          validator: optional function called to validate the option's value
-            (Default value = None)
-          converter: optional function to be called to convert the option's
-            value before putting it in the environment. (Default value = None)
-          kw: keyword args, unused.
+        """
+        Add an option.
 
+
+        @param key: the name of the variable, or a list or tuple of arguments
+        @param help: optional help text for the options
+        @param default: optional default value
+        @param validator: optional function that is called to validate the option's value
+        @type validator: Called with (key, value, environment)
+        @param converter: optional function that is called to convert the option's value before putting it in the environment.
         """
+
         if SCons.Util.is_List(key) or isinstance(key, tuple):
             self._do_add(*key)
             return

SCons/cpp.py

@@ -603,7 +603,8 @@ def resolve_include(self, t):
 
         This handles recursive expansion of values without "" or <>
         surrounding the name until an initial " or < is found, to handle
-        #include FILE where FILE is a #define somewhere else.
+                #include FILE
+        where FILE is a #define somewhere else.
         """
         s = t[1].strip()
         while not s[0] in '<"':