From 261f1d187b92adfbe262e0fad394743c8c0f80be Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 30 May 2020 08:13:35 -0600 Subject: 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 --- SCons/Environment.py | 39 +++++++++++++++------------------------ SCons/Errors.py | 7 +++++-- SCons/Platform/__init__.py | 18 +++++++----------- SCons/Script/SConsOptions.py | 6 ++---- SCons/Tool/dmd.py | 35 ++++++++++++----------------------- SCons/Tool/intelc.py | 14 +++++++------- SCons/Tool/packaging/rpm.py | 22 ++++++++++------------ SCons/Util.py | 27 +++++++++++---------------- SCons/Variables/__init__.py | 43 ++++++++++++++++++------------------------- SCons/cpp.py | 3 ++- SCons/dblite.py | 1 - 11 files changed, 89 insertions(+), 126 deletions(-) diff --git a/SCons/Environment.py b/SCons/Environment.py index c30a661..cd52ee5 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1502,16 +1502,11 @@ class Base(SubstitutionEnvironment): 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 @@ class Base(SubstitutionEnvironment): 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 @@ class Base(SubstitutionEnvironment): 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 @@ class Base(SubstitutionEnvironment): pass else: del kw['target_factory'] - + bld = SCons.Builder.Builder(**bkw) return bld(self, target, source, **kw) diff --git a/SCons/Errors.py b/SCons/Errors.py index 882ae82..a3a891f 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -35,11 +35,13 @@ import SCons.Util 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) diff --git a/SCons/Platform/__init__.py b/SCons/Platform/__init__.py index 20048ee..12db824 100644 --- a/SCons/Platform/__init__.py +++ b/SCons/Platform/__init__.py @@ -56,10 +56,10 @@ import SCons.Tool 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 @@ class PlatformSpec: 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 diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py index ffd3c4a..10600b6 100644 --- a/SCons/Script/SConsOptions.py +++ b/SCons/Script/SConsOptions.py @@ -346,9 +346,8 @@ class SConsOptionParser(optparse.OptionParser): 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. @@ -356,7 +355,6 @@ class SConsOptionParser(optparse.OptionParser): _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). diff --git a/SCons/Tool/dmd.py b/SCons/Tool/dmd.py index 32b9c02..3cc4ed0 100644 --- a/SCons/Tool/dmd.py +++ b/SCons/Tool/dmd.py @@ -10,33 +10,22 @@ Evolved by Russel Winder (russel@winder.org.uk) 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) """ # diff --git a/SCons/Tool/intelc.py b/SCons/Tool/intelc.py index 2242e60..0880976 100644 --- a/SCons/Tool/intelc.py +++ b/SCons/Tool/intelc.py @@ -387,13 +387,13 @@ def get_intel_compiler_top(version, abi): 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 diff --git a/SCons/Tool/packaging/rpm.py b/SCons/Tool/packaging/rpm.py index 9e2bbb0..0e44bf9 100644 --- a/SCons/Tool/packaging/rpm.py +++ b/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): diff --git a/SCons/Util.py b/SCons/Util.py index effe4c4..1ec0cf8 100644 --- a/SCons/Util.py +++ b/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: diff --git a/SCons/Variables/__init__.py b/SCons/Variables/__init__.py index 832ee58..59b63eb 100644 --- a/SCons/Variables/__init__.py +++ b/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 @@ class Variables: 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 diff --git a/SCons/cpp.py b/SCons/cpp.py index 0811c71..1113be5 100644 --- a/SCons/cpp.py +++ b/SCons/cpp.py @@ -603,7 +603,8 @@ class PreProcessor: 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 '<"': diff --git a/SCons/dblite.py b/SCons/dblite.py index 338dcc7..b9269f1 100644 --- a/SCons/dblite.py +++ b/SCons/dblite.py @@ -37,7 +37,6 @@ class dblite: See the discussion at: http://mail.python.org/pipermail/python-bugs-list/2003-March/016877.html - """ _open = open -- cgit v0.12