From 455cae01c29d6da491507b277bf9ec33b0fdcb16 Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Thu, 27 Apr 2017 07:45:34 -0700
Subject: [PATCH] Convert rest docstrings to Google docstrings. (#3994)

- Sometimes you need something mindless to do.
- Sometimes it can be helpful, as well.
---
 lib/spack/llnl/util/filesystem.py       |  71 ++++++++-------
 lib/spack/spack/build_environment.py    |  52 ++++++-----
 lib/spack/spack/build_systems/python.py |   8 +-
 lib/spack/spack/cmd/checksum.py         |  13 +--
 lib/spack/spack/cmd/create.py           |  45 ++++++----
 lib/spack/spack/cmd/edit.py             |   7 +-
 lib/spack/spack/cmd/url.py              |  48 +++++-----
 lib/spack/spack/directives.py           |  20 +++--
 lib/spack/spack/environment.py          |  13 +--
 lib/spack/spack/fetch_strategy.py       |  15 +++-
 lib/spack/spack/mirror.py               |   9 +-
 lib/spack/spack/package.py              | 113 +++++++++++++-----------
 lib/spack/spack/spec.py                 |  50 ++++++-----
 lib/spack/spack/test/modules.py         |  10 ++-
 lib/spack/spack/test/python_version.py  |   9 +-
 lib/spack/spack/url.py                  | 108 ++++++++++++----------
 lib/spack/spack/util/naming.py          |  12 ++-
 lib/spack/spack/util/pattern.py         |  25 +++---
 18 files changed, 352 insertions(+), 276 deletions(-)

diff --git a/lib/spack/llnl/util/filesystem.py b/lib/spack/llnl/util/filesystem.py
index 86122f42c8..035f9a13ff 100644
--- a/lib/spack/llnl/util/filesystem.py
+++ b/lib/spack/llnl/util/filesystem.py
@@ -584,32 +584,32 @@ def __str__(self):
         return self.joined()
 
 
-def find_system_libraries(args, shared=True):
-    """Searches the usual system library locations for the libraries
-    specified in args.
+def find_system_libraries(library_names, shared=True):
+    """Searches the usual system library locations for ``library_names``.
 
     Search order is as follows:
 
-    1. /lib64
-    2. /lib
-    3. /usr/lib64
-    4. /usr/lib
-    5. /usr/local/lib64
-    6. /usr/local/lib
+    1. ``/lib64``
+    2. ``/lib``
+    3. ``/usr/lib64``
+    4. ``/usr/lib``
+    5. ``/usr/local/lib64``
+    6. ``/usr/local/lib``
 
-    :param args: Library name(s) to search for
-    :type args: str or collections.Sequence
-    :param bool shared: if True searches for shared libraries,
+    Args:
+        library_names (str or list of str): Library name(s) to search for
+        shared (bool): searches for shared libraries if True
 
-    :returns: The libraries that have been found
-    :rtype: LibraryList
+    Returns:
+        LibraryList: The libraries that have been found
     """
-    if isinstance(args, str):
-        args = [args]
-    elif not isinstance(args, collections.Sequence):
+    if isinstance(library_names, str):
+        library_names = [library_names]
+    elif not isinstance(library_names, collections.Sequence):
         message = '{0} expects a string or sequence of strings as the '
         message += 'first argument [got {1} instead]'
-        message = message.format(find_system_libraries.__name__, type(args))
+        message = message.format(
+            find_system_libraries.__name__, type(library_names))
         raise TypeError(message)
 
     libraries_found = []
@@ -622,7 +622,7 @@ def find_system_libraries(args, shared=True):
         '/usr/local/lib',
     ]
 
-    for library in args:
+    for library in library_names:
         for root in search_locations:
             result = find_libraries(library, root, shared, recurse=True)
             if result:
@@ -632,27 +632,26 @@ def find_system_libraries(args, shared=True):
     return libraries_found
 
 
-def find_libraries(args, root, shared=True, recurse=False):
-    """Returns an iterable object containing a list of full paths to
-    libraries if found.
+def find_libraries(library_names, root, shared=True, recurse=False):
+    """Returns an iterable of full paths to libraries found in a root dir.
 
-    :param args: Library name(s) to search for
-    :type args: str or collections.Sequence
-    :param str root: The root directory to start searching from
-    :param bool shared: if True searches for shared libraries,
-        otherwise for static
-    :param bool recurse: if False search only root folder,
-        if True descends top-down from the root
+    Args:
+        library_names (str or list of str): Library names to search for
+        root (str): The root directory to start searching from
+        shared (bool): if True searches for shared libraries, otherwise static.
+        recurse (bool): if False search only root folder,
+            if True descends top-down from the root
 
-    :returns: The libraries that have been found
-    :rtype: LibraryList
+    Returns:
+        LibraryList: The libraries that have been found
     """
-    if isinstance(args, str):
-        args = [args]
-    elif not isinstance(args, collections.Sequence):
+    if isinstance(library_names, str):
+        library_names = [library_names]
+    elif not isinstance(library_names, collections.Sequence):
         message = '{0} expects a string or sequence of strings as the '
         message += 'first argument [got {1} instead]'
-        raise TypeError(message.format(find_libraries.__name__, type(args)))
+        raise TypeError(message.format(
+            find_libraries.__name__, type(library_names)))
 
     # Construct the right suffix for the library
     if shared is True:
@@ -660,7 +659,7 @@ def find_libraries(args, root, shared=True, recurse=False):
     else:
         suffix = 'a'
     # List of libraries we are searching with suffixes
-    libraries = ['{0}.{1}'.format(lib, suffix) for lib in args]
+    libraries = ['{0}.{1}'.format(lib, suffix) for lib in library_names]
     # Search method
     if recurse is False:
         search_method = _find_libraries_non_recursive
diff --git a/lib/spack/spack/build_environment.py b/lib/spack/spack/build_environment.py
index 06ac65f552..9c3768b65b 100644
--- a/lib/spack/spack/build_environment.py
+++ b/lib/spack/spack/build_environment.py
@@ -438,12 +438,17 @@ def get_rpaths(pkg):
 
 
 def get_std_cmake_args(pkg):
-    """Returns the list of standard arguments that would be used if this
-    package was a CMakePackage instance.
+    """List of standard arguments used if a package is a CMakePackage.
 
-    :param pkg: pkg under consideration
+    Returns:
+        list of str: standard arguments that would be used if this
+        package were a CMakePackage instance.
 
-    :return: list of arguments for cmake
+    Args:
+        pkg (PackageBase): package under consideration
+
+    Returns:
+        list of str: arguments for cmake
     """
     return spack.CMakePackage._std_args(pkg)
 
@@ -465,10 +470,13 @@ def parent_class_modules(cls):
 
 
 def load_external_modules(pkg):
-    """Traverse the spec list associated with a package
-    and find any specs that have external modules.
+    """Traverse a package's spec DAG and load any external modules.
 
-    :param pkg: package under consideration
+    Traverse a package's dependencies and load any external modules
+    associated with them.
+
+    Args:
+        pkg (PackageBase): package to load deps for
     """
     for dep in list(pkg.spec.traverse()):
         if dep.external_module:
@@ -531,25 +539,29 @@ def setup_package(pkg, dirty=False):
 def fork(pkg, function, dirty=False):
     """Fork a child process to do part of a spack build.
 
-    :param pkg: pkg whose environemnt we should set up the forked process for.
-    :param function: arg-less function to run in the child process.
-    :param dirty: If True, do NOT clean the environment before building.
+    Args:
+
+        pkg (PackageBase): package whose environemnt we should set up the
+            forked process for.
+        function (callable): argless function to run in the child
+            process.
+        dirty (bool): If True, do NOT clean the environment before
+            building.
 
     Usage::
 
-       def child_fun():
-           # do stuff
-       build_env.fork(pkg, child_fun)
+        def child_fun():
+            # do stuff
+        build_env.fork(pkg, child_fun)
 
     Forked processes are run with the build environment set up by
-    spack.build_environment.  This allows package authors to have
-    full control over the environment, etc. without affecting
-    other builds that might be executed in the same spack call.
+    spack.build_environment.  This allows package authors to have full
+    control over the environment, etc. without affecting other builds
+    that might be executed in the same spack call.
 
-    If something goes wrong, the child process is expected to print
-    the error and the parent process will exit with error as
-    well. If things go well, the child exits and the parent
-    carries on.
+    If something goes wrong, the child process is expected to print the
+    error and the parent process will exit with error as well. If things
+    go well, the child exits and the parent carries on.
     """
 
     def child_execution(child_connection, input_stream):
diff --git a/lib/spack/spack/build_systems/python.py b/lib/spack/spack/build_systems/python.py
index 7a8650bfce..3fae6671f0 100644
--- a/lib/spack/spack/build_systems/python.py
+++ b/lib/spack/spack/build_systems/python.py
@@ -137,9 +137,11 @@ def setup_py(self, *args, **kwargs):
     def _setup_command_available(self, command):
         """Determines whether or not a setup.py command exists.
 
-        :param str command: The command to look for
-        :return: True if the command is found, else False
-        :rtype: bool
+        Args:
+            command (str): The command to look for
+
+        Returns:
+            bool: True if the command is found, else False
         """
         kwargs = {
             'output': os.devnull,
diff --git a/lib/spack/spack/cmd/checksum.py b/lib/spack/spack/cmd/checksum.py
index e0b7fd897d..fda9beed27 100644
--- a/lib/spack/spack/cmd/checksum.py
+++ b/lib/spack/spack/cmd/checksum.py
@@ -57,13 +57,14 @@ def get_checksums(url_dict, name, **kwargs):
     The ``first_stage_function`` kwarg allows ``spack create`` to determine
     things like the build system of the archive.
 
-    :param dict url_dict: A dictionary of the form: version -> URL
-    :param str name: The name of the package
-    :param callable first_stage_function: Function to run on first staging area
-    :param bool keep_stage: Don't clean up staging area when command completes
+    Args:
+        url_dict (dict): A dictionary of the form: version -> URL
+        name (str): The name of the package
+        first_stage_function (callable): Function to run on first staging area
+        keep_stage (bool): Don't clean up staging area when command completes
 
-    :returns: A multi-line string containing versions and corresponding hashes
-    :rtype: str
+    Returns:
+        str: A multi-line string containing versions and corresponding hashes
     """
     first_stage_function = kwargs.get('first_stage_function', None)
     keep_stage = kwargs.get('keep_stage', False)
diff --git a/lib/spack/spack/cmd/create.py b/lib/spack/spack/cmd/create.py
index d839cc91ad..504ac9d844 100644
--- a/lib/spack/spack/cmd/create.py
+++ b/lib/spack/spack/cmd/create.py
@@ -451,10 +451,12 @@ def get_name(args):
     If a name was provided, always use that. Otherwise, if a URL was
     provided, extract the name from that. Otherwise, use a default.
 
-    :param argparse.Namespace args: The arguments given to ``spack create``
+    Args:
+        args (param argparse.Namespace): The arguments given to
+            ``spack create``
 
-    :returns: The name of the package
-    :rtype: str
+    Returns:
+        str: The name of the package
     """
 
     # Default package name
@@ -487,10 +489,11 @@ def get_url(args):
 
     Use a default URL if none is provided.
 
-    :param argparse.Namespace args: The arguments given to ``spack create``
+    Args:
+        args (argparse.Namespace): The arguments given to ``spack create``
 
-    :returns: The URL of the package
-    :rtype: str
+    Returns:
+        str: The URL of the package
     """
 
     # Default URL
@@ -510,11 +513,13 @@ def get_versions(args, name):
 
     Returns default values if no URL is provided.
 
-    :param argparse.Namespace args: The arguments given to ``spack create``
-    :param str name: The name of the package
+    Args:
+        args (argparse.Namespace): The arguments given to ``spack create``
+        name (str): The name of the package
 
-    :returns: Versions and hashes, and a BuildSystemGuesser object
-    :rtype: str and BuildSystemGuesser
+    Returns:
+        str and BuildSystemGuesser: Versions and hashes, and a
+            BuildSystemGuesser object
     """
 
     # Default version, hash, and guesser
@@ -552,12 +557,13 @@ def get_build_system(args, guesser):
     is provided, download the tarball and peek inside to guess what
     build system it uses. Otherwise, use a generic template by default.
 
-    :param argparse.Namespace args: The arguments given to ``spack create``
-    :param BuildSystemGuesser guesser: The first_stage_function given to \
-        ``spack checksum`` which records the build system it detects
+    Args:
+        args (argparse.Namespace): The arguments given to ``spack create``
+        guesser (BuildSystemGuesser): The first_stage_function given to
+            ``spack checksum`` which records the build system it detects
 
-    :returns: The name of the build system template to use
-    :rtype: str
+    Returns:
+        str: The name of the build system template to use
     """
 
     # Default template
@@ -584,11 +590,12 @@ def get_repository(args, name):
     """Returns a Repo object that will allow us to determine the path where
     the new package file should be created.
 
-    :param argparse.Namespace args: The arguments given to ``spack create``
-    :param str name: The name of the package to create
+    Args:
+        args (argparse.Namespace): The arguments given to ``spack create``
+        name (str): The name of the package to create
 
-    :returns: A Repo object capable of determining the path to the package file
-    :rtype: Repo
+    Returns:
+        Repo: A Repo object capable of determining the path to the package file
     """
     spec = Spec(name)
     # Figure out namespace for spec
diff --git a/lib/spack/spack/cmd/edit.py b/lib/spack/spack/cmd/edit.py
index f439736192..01f2b61887 100644
--- a/lib/spack/spack/cmd/edit.py
+++ b/lib/spack/spack/cmd/edit.py
@@ -38,9 +38,10 @@
 def edit_package(name, repo_path, namespace):
     """Opens the requested package file in your favorite $EDITOR.
 
-    :param str name: The name of the package
-    :param str repo_path: The path to the repository containing this package
-    :param str namespace: A valid namespace registered with Spack
+    Args:
+        name (str): The name of the package
+        repo_path (str): The path to the repository containing this package
+        namespace (str): A valid namespace registered with Spack
     """
     # Find the location of the package
     if repo_path:
diff --git a/lib/spack/spack/cmd/url.py b/lib/spack/spack/cmd/url.py
index 1128e08a43..e5cfce0de3 100644
--- a/lib/spack/spack/cmd/url.py
+++ b/lib/spack/spack/cmd/url.py
@@ -244,7 +244,8 @@ def print_name_and_version(url):
     """Prints a URL. Underlines the detected name with dashes and
     the detected version with tildes.
 
-    :param str url: The url to parse
+    Args:
+        url (str): The url to parse
     """
     name, ns, nl, ntup, ver, vs, vl, vtup = substitution_offsets(url)
     underlines = [' '] * max(ns + nl, vs + vl)
@@ -260,13 +261,15 @@ def print_name_and_version(url):
 def url_list_parsing(args, urls, url, pkg):
     """Helper function for :func:`url_list`.
 
-    :param argparse.Namespace args: The arguments given to ``spack url list``
-    :param set urls: List of URLs that have already been added
-    :param url: A URL to potentially add to ``urls`` depending on ``args``
-    :type url: str or None
-    :param spack.package.PackageBase pkg: The Spack package
-    :returns: The updated ``urls`` list
-    :rtype: set
+    Args:
+        args (argparse.Namespace): The arguments given to ``spack url list``
+        urls (set): List of URLs that have already been added
+        url (str or None): A URL to potentially add to ``urls`` depending on
+            ``args``
+        pkg (spack.package.PackageBase): The Spack package
+
+    Returns:
+        set: The updated set of ``urls``
     """
     if url:
         if args.correct_name or args.incorrect_name:
@@ -310,10 +313,12 @@ def url_list_parsing(args, urls, url, pkg):
 def name_parsed_correctly(pkg, name):
     """Determine if the name of a package was correctly parsed.
 
-    :param spack.package.PackageBase pkg: The Spack package
-    :param str name: The name that was extracted from the URL
-    :returns: True if the name was correctly parsed, else False
-    :rtype: bool
+    Args:
+        pkg (spack.package.PackageBase): The Spack package
+        name (str): The name that was extracted from the URL
+
+    Returns:
+        bool: True if the name was correctly parsed, else False
     """
     pkg_name = pkg.name
 
@@ -336,10 +341,12 @@ def name_parsed_correctly(pkg, name):
 def version_parsed_correctly(pkg, version):
     """Determine if the version of a package was correctly parsed.
 
-    :param spack.package.PackageBase pkg: The Spack package
-    :param str version: The version that was extracted from the URL
-    :returns: True if the name was correctly parsed, else False
-    :rtype: bool
+    Args:
+        pkg (spack.package.PackageBase): The Spack package
+        version (str): The version that was extracted from the URL
+
+    Returns:
+        bool: True if the name was correctly parsed, else False
     """
     version = remove_separators(version)
 
@@ -359,10 +366,11 @@ def remove_separators(version):
     Make sure 1.2.3, 1-2-3, 1_2_3, and 123 are considered equal.
     Unfortunately, this also means that 1.23 and 12.3 are equal.
 
-    :param version: A version
-    :type version: str or Version
-    :returns: The version with all separator characters removed
-    :rtype: str
+    Args:
+        version (str or Version): A version
+
+    Returns:
+        str: The version with all separator characters removed
     """
     version = str(version)
 
diff --git a/lib/spack/spack/directives.py b/lib/spack/spack/directives.py
index e2219d1f49..7a245f606c 100644
--- a/lib/spack/spack/directives.py
+++ b/lib/spack/spack/directives.py
@@ -265,20 +265,22 @@ def _depends_on(pkg, spec, when=None, type=None):
 
 @directive('conflicts')
 def conflicts(conflict_spec, when=None):
-    """Allows a package to define a conflict, i.e. a concretized configuration
-    that is known to be non-valid.
+    """Allows a package to define a conflict.
 
-    For example a package that is known not to be buildable with intel
-    compilers can declare:
+    Currently, a "conflict" is a concretized configuration that is known
+    to be non-valid. For example, a package that is known not to be
+    buildable with intel compilers can declare::
 
-    conflicts('%intel')
+        conflicts('%intel')
 
-    To express the same constraint only when the 'foo' variant is activated:
+    To express the same constraint only when the 'foo' variant is
+    activated::
 
-    conflicts('%intel', when='+foo')
+        conflicts('%intel', when='+foo')
 
-    :param conflict_spec: constraint defining the known conflict
-    :param when: optional constraint that triggers the conflict
+    Args:
+        conflict_spec (Spec): constraint defining the known conflict
+        when (Spec): optional constraint that triggers the conflict
     """
     def _execute(pkg):
         # If when is not specified the conflict always holds
diff --git a/lib/spack/spack/environment.py b/lib/spack/spack/environment.py
index eadfa45efb..83a5139410 100644
--- a/lib/spack/spack/environment.py
+++ b/lib/spack/spack/environment.py
@@ -262,12 +262,15 @@ def apply_modifications(self):
 
     @staticmethod
     def from_sourcing_files(*args, **kwargs):
-        """Creates an instance of EnvironmentModifications that, if executed,
-        has the same effect on the environment as sourcing the files passed as
-        parameters
+        """Returns modifications that would be made by sourcing files.
 
-        :param \*args: list of files to be sourced
-        :rtype: instance of EnvironmentModifications
+        Args:
+            *args (list of str): list of files to be sourced
+
+        Returns:
+            EnvironmentModifications: an object that, if executed, has
+                the same effect on the environment as sourcing the files
+                passed as parameters
         """
         env = EnvironmentModifications()
 
diff --git a/lib/spack/spack/fetch_strategy.py b/lib/spack/spack/fetch_strategy.py
index c694610856..5c872ae1b6 100644
--- a/lib/spack/spack/fetch_strategy.py
+++ b/lib/spack/spack/fetch_strategy.py
@@ -911,11 +911,18 @@ def from_url(url):
 
 
 def from_kwargs(**kwargs):
-    """
-    Construct the appropriate FetchStrategy from the given keyword arguments.
+    """Construct an appropriate FetchStrategy from the given keyword arguments.
 
-    :param kwargs: dictionary of keyword arguments
-    :return: fetcher or raise a FetchError exception
+    Args:
+        **kwargs: dictionary of keyword arguments, e.g. from a
+            ``version()`` directive in a package.
+
+    Returns:
+        fetch_strategy: The fetch strategy that matches the args, based
+            on attribute names (e.g., ``git``, ``hg``, etc.)
+
+    Raises:
+        FetchError: If no ``fetch_strategy`` matches the args.
     """
     for fetcher in all_strategies:
         if fetcher.matches(kwargs):
diff --git a/lib/spack/spack/mirror.py b/lib/spack/spack/mirror.py
index aef5e2e8ee..c9ed617dc8 100644
--- a/lib/spack/spack/mirror.py
+++ b/lib/spack/spack/mirror.py
@@ -117,13 +117,10 @@ def get_matching_versions(specs, **kwargs):
 
 
 def suggest_archive_basename(resource):
-    """
-    Return a tentative basename for an archive.
+    """Return a tentative basename for an archive.
 
-    Raises an exception if the name is not an allowed archive type.
-
-    :param fetcher:
-    :return:
+    Raises:
+        RuntimeError: if the name is not an allowed archive type.
     """
     basename = os.path.basename(resource.fetcher.url)
     if not allowed_archive(basename):
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
index 506e44ec45..4d93b6304c 100644
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -73,7 +73,7 @@
 
 
 class InstallPhase(object):
-    """Manages a single phase of the installation
+    """Manages a single phase of the installation.
 
     This descriptor stores at creation time the name of the method it should
     search for execution. The method is retrieved at __get__ time, so that
@@ -214,11 +214,14 @@ def run_after(*phases):
 
 
 def on_package_attributes(**attr_dict):
-    """Executes the decorated method only if at the moment of calling
-    the instance has attributes that are equal to certain values.
+    """Decorator: executes instance function only if object has attr valuses.
 
-    :param dict attr_dict: dictionary mapping attribute names to their
-        required values
+    Executes the decorated method only if at the moment of calling the
+    instance has attributes that are equal to certain values.
+
+    Args:
+        attr_dict (dict): dictionary mapping attribute names to their
+            required values
     """
     def _execute_under_condition(func):
 
@@ -1082,12 +1085,14 @@ def _stage_and_write_lock(self):
                 yield
 
     def _process_external_package(self, explicit):
-        """Helper function to process external packages. It runs post install
-        hooks and registers the package in the DB.
+        """Helper function to process external packages.
 
-        :param bool explicit: True if the package was requested explicitly by
-            the user, False if it was pulled in as a dependency of an explicit
-            package.
+        Runs post install hooks and registers the package in the DB.
+
+        Args:
+            explicit (bool): if the package was requested explicitly by
+                the user, False if it was pulled in as a dependency of an
+                explicit package.
         """
         if self.spec.external_module:
             message = '{s.name}@{s.version} : has external module in {module}'
@@ -1143,24 +1148,25 @@ def do_install(self,
         Package implementations should override install() to describe
         their build process.
 
-        :param bool keep_prefix: Keep install prefix on failure. By default,
-            destroys it.
-        :param bool keep_stage: By default, stage is destroyed only if there
-            are no exceptions during build. Set to True to keep the stage
-            even with exceptions.
-        :param bool install_deps: Install dependencies before installing this
-            package
-        :param bool skip_patch: Skip patch stage of build if True.
-        :param bool verbose: Display verbose build output (by default,
-            suppresses it)
-        :param int make_jobs: Number of make jobs to use for install. Default
-            is ncpus
-        :param bool run_tests: Run tests within the package's install()
-        :param bool fake: Don't really build; install fake stub files instead.
-        :param bool explicit: True if package was explicitly installed, False
-            if package was implicitly installed (as a dependency).
-        :param bool dirty: Don't clean the build environment before installing.
-        :param bool force: Install again, even if already installed.
+        Args:
+            keep_prefix (bool): Keep install prefix on failure. By default,
+                destroys it.
+            keep_stage (bool): By default, stage is destroyed only if there
+                are no exceptions during build. Set to True to keep the stage
+                even with exceptions.
+            install_deps (bool): Install dependencies before installing this
+                package
+            skip_patch (bool): Skip patch stage of build if True.
+            verbose (bool): Display verbose build output (by default,
+                suppresses it)
+            make_jobs (int): Number of make jobs to use for install. Default
+                is ncpus
+            run_tests (bool): Run tests within the package's install()
+            fake (bool): Don't really build; install fake stub files instead.
+            explicit (bool): True if package was explicitly installed, False
+                if package was implicitly installed (as a dependency).
+            dirty (bool): Don't clean the build environment before installing.
+            force (bool): Install again, even if already installed.
         """
         if not self.spec.concrete:
             raise ValueError("Can only install concrete packages: %s."
@@ -1423,12 +1429,13 @@ def setup_environment(self, spack_env, run_env):
 
         1. Qt extensions need ``QTDIR`` set.
 
-        :param EnvironmentModifications spack_env: List of environment
-            modifications to be applied when this package is built
-            within Spack.
-        :param EnvironmentModifications run_env: List of environment
-            modifications to be applied when this package is run outside
-            of Spack. These are added to the resulting module file.
+        Args:
+            spack_env (EnvironmentModifications): List of environment
+                modifications to be applied when this package is built
+                within Spack.
+            run_env (EnvironmentModifications): List of environment
+                modifications to be applied when this package is run outside
+                of Spack. These are added to the resulting module file.
         """
         pass
 
@@ -1450,17 +1457,18 @@ def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
            to the ``lib/pythonX.Y/site-packages`` directory in the module's
            install prefix. This method could be used to set that variable.
 
-        :param EnvironmentModifications spack_env: List of environment
-            modifications to be applied when the dependent package is
-            built within Spack.
-        :param EnvironmentModifications run_env: List of environment
-            modifications to be applied when the dependent package is
-            run outside of Spack. These are added to the resulting
-            module file.
-        :param Spec dependent_spec: The spec of the dependent package
-            about to be built. This allows the extendee (self) to query
-            the dependent's state. Note that *this* package's spec is
-            available as ``self.spec``.
+        Args:
+            spack_env (EnvironmentModifications): List of environment
+                modifications to be applied when the dependent package is
+                built within Spack.
+            run_env (EnvironmentModifications): List of environment
+                modifications to be applied when the dependent package is
+                run outside of Spack. These are added to the resulting
+                module file.
+            dependent_spec (Spec): The spec of the dependent package
+                about to be built. This allows the extendee (self) to query
+                the dependent's state. Note that *this* package's spec is
+                available as ``self.spec``.
         """
         pass
 
@@ -1489,14 +1497,15 @@ def setup_dependent_package(self, module, dependent_spec):
            indicating the path to their libraries, since these
            paths differ by BLAS/LAPACK implementation.
 
-        :param spack.package.PackageBase.module module: The Python ``module``
-            object of the dependent package. Packages can use this to set
-            module-scope variables for the dependent to use.
+        Args:
+            module (spack.package.PackageBase.module): The Python ``module``
+                object of the dependent package. Packages can use this to set
+                module-scope variables for the dependent to use.
 
-        :param Spec dependent_spec: The spec of the dependent package
-            about to be built. This allows the extendee (self) to
-            query the dependent's state.  Note that *this*
-            package's spec is available as ``self.spec``.
+            dependent_spec (Spec): The spec of the dependent package
+                about to be built. This allows the extendee (self) to
+                query the dependent's state.  Note that *this*
+                package's spec is available as ``self.spec``.
         """
         pass
 
diff --git a/lib/spack/spack/spec.py b/lib/spack/spack/spec.py
index 3d067e083f..4cd89f59bf 100644
--- a/lib/spack/spack/spec.py
+++ b/lib/spack/spack/spec.py
@@ -758,32 +758,35 @@ def __str__(self):
 
 
 def _libs_default_handler(descriptor, spec, cls):
-    """Default handler when looking for 'libs' attribute. The default
-    tries to search for 'lib{spec.name}' recursively starting from
+    """Default handler when for ``libs`` attribute in Spec interface.
+
+    Tries to search for ``lib{spec.name}`` recursively starting from
     `spec.prefix`.
 
-    :param ForwardQueryToPackage descriptor: descriptor that triggered
-        the call
-    :param Spec spec: spec that is being queried
-    :param type(spec) cls: type of spec, to match the signature of the
-        descriptor `__get__` method
+    Args:
+        descriptor (ForwardQueryToPackage): descriptor that triggered
+            the call
+        spec (Spec): spec that is being queried
+        cls (type(spec)): type of spec, to match the signature of the
+            descriptor `__get__` method
     """
     name = 'lib' + spec.name
     shared = '+shared' in spec
-    return find_libraries(
-        name, root=spec.prefix, shared=shared, recurse=True
-    )
+    return find_libraries(name, root=spec.prefix, shared=shared, recurse=True)
 
 
 def _cppflags_default_handler(descriptor, spec, cls):
-    """Default handler when looking for cppflags attribute. The default
-    just returns '-I{spec.prefix.include}'.
+    """Default handler for the ``cppflags`` attribute in the Spec interface.
 
-    :param ForwardQueryToPackage descriptor: descriptor that triggered
-        the call
-    :param Spec spec: spec that is being queried
-    :param type(spec) cls: type of spec, to match the signature of the
-        descriptor `__get__` method
+    The default just returns ``-I{spec.prefix.include}``.
+
+    Args:
+        descriptor (ForwardQueryToPackage): descriptor that triggered
+            the call
+        spec (Spec): spec that is being queried
+
+        cls (type(spec)): type of spec, to match the signature of the
+            descriptor ``__get__`` method
     """
     return '-I' + spec.prefix.include
 
@@ -792,13 +795,14 @@ class ForwardQueryToPackage(object):
     """Descriptor used to forward queries from Spec to Package"""
 
     def __init__(self, attribute_name, default_handler=None):
-        """Initializes the instance of the descriptor
+        """Create a new descriptor.
 
-        :param str attribute_name: name of the attribute to be
-            searched for in the Package instance
-        :param callable default_handler: [optional] default function
-            to be called if the attribute was not found in the Package
-            instance
+        Args:
+            attribute_name (str): name of the attribute to be
+                searched for in the Package instance
+            default_handler (callable, optional): default function to be
+                called if the attribute was not found in the Package
+                instance
         """
         self.attribute_name = attribute_name
         # Turn the default handler into a function with the right
diff --git a/lib/spack/spack/test/modules.py b/lib/spack/spack/test/modules.py
index 0eb54cba2c..e8ebebf736 100644
--- a/lib/spack/spack/test/modules.py
+++ b/lib/spack/spack/test/modules.py
@@ -63,10 +63,12 @@ def _mock(filename, mode):
 def get_modulefile_content(factory, spec):
     """Writes the module file and returns the content as a string.
 
-    :param factory: module file factory
-    :param spec: spec of the module file to be written
-    :return: content of the module file
-    :rtype: str
+    Args:
+        factory: module file factory
+        spec: spec of the module file to be written
+
+    Returns:
+        str: content of the module file
     """
     spec.concretize()
     generator = factory(spec)
diff --git a/lib/spack/spack/test/python_version.py b/lib/spack/spack/test/python_version.py
index d58df1a0aa..35b6ad7da7 100644
--- a/lib/spack/spack/test/python_version.py
+++ b/lib/spack/spack/test/python_version.py
@@ -67,9 +67,12 @@
 def pyfiles(search_paths, exclude=()):
     """Generator that yields all the python files in the search paths.
 
-    :param search_paths: list of paths to search for python files
-    :param exclude: file paths to exclude from search
-    :return: python files
+    Args:
+        search_paths (list of str): list of paths to search for python files
+        exclude (list of str): file paths to exclude from search
+
+    Yields:
+        python files in the search path.
     """
     # first file is the spack script.
     yield spack.spack_file
diff --git a/lib/spack/spack/url.py b/lib/spack/spack/url.py
index 7a597073d6..736c0f2efd 100644
--- a/lib/spack/spack/url.py
+++ b/lib/spack/spack/url.py
@@ -116,9 +116,11 @@ def strip_version_suffixes(path):
     * ``libevent-2.0.21``
     * ``cuda_8.0.44``
 
-    :param str path: The filename or URL for the package
-    :return: The ``path`` with any extraneous suffixes removed
-    :rtype: str
+    Args:
+        path (str): The filename or URL for the package
+
+    Returns:
+        str: The ``path`` with any extraneous suffixes removed
     """
     # NOTE: This could be done with complicated regexes in parse_version_offset
     # NOTE: The problem is that we would have to add these regexes to the end
@@ -227,10 +229,12 @@ def strip_name_suffixes(path, version):
     * ``converge``
     * ``jpeg``
 
-    :param str path: The filename or URL for the package
-    :param str version: The version detected for this URL
-    :return: The ``path`` with any extraneous suffixes removed
-    :rtype: str
+    Args:
+        path (str): The filename or URL for the package
+        version (str): The version detected for this URL
+
+    Returns:
+        str: The ``path`` with any extraneous suffixes removed
     """
     # NOTE: This could be done with complicated regexes in parse_name_offset
     # NOTE: The problem is that we would have to add these regexes to every
@@ -339,18 +343,19 @@ def determine_url_file_extension(path):
 def parse_version_offset(path):
     """Try to extract a version string from a filename or URL.
 
-    :param str path: The filename or URL for the package
+    Args:
+        path (str): The filename or URL for the package
 
-    :return: A tuple containing:
-        version of the package,
-        first index of version,
-        length of version string,
-        the index of the matching regex
-        the matching regex
+    Returns:
+        tuple of (Version, int, int, int, str): A tuple containing:
+            version of the package,
+            first index of version,
+            length of version string,
+            the index of the matching regex
+            the matching regex
 
-    :rtype: tuple
-
-    :raises UndetectableVersionError: If the URL does not match any regexes
+    Raises:
+        UndetectableVersionError: If the URL does not match any regexes
     """
     original_path = path
 
@@ -524,12 +529,14 @@ def parse_version_offset(path):
 def parse_version(path):
     """Try to extract a version string from a filename or URL.
 
-    :param str path: The filename or URL for the package
+    Args:
+        path (str): The filename or URL for the package
 
-    :return: The version of the package
-    :rtype: spack.version.Version
+    Returns:
+        spack.version.Version: The version of the package
 
-    :raises UndetectableVersionError: If the URL does not match any regexes
+    Raises:
+        UndetectableVersionError: If the URL does not match any regexes
     """
     version, start, length, i, regex = parse_version_offset(path)
     return Version(version)
@@ -538,19 +545,20 @@ def parse_version(path):
 def parse_name_offset(path, v=None):
     """Try to determine the name of a package from its filename or URL.
 
-    :param str path: The filename or URL for the package
-    :param str v: The version of the package
+    Args:
+        path (str): The filename or URL for the package
+        v (str): The version of the package
 
-    :return: A tuple containing:
-        name of the package,
-        first index of name,
-        length of name,
-        the index of the matching regex
-        the matching regex
+    Returns:
+        tuple of (str, int, int, int, str): A tuple containing:
+            name of the package,
+            first index of name,
+            length of name,
+            the index of the matching regex
+            the matching regex
 
-    :rtype: tuple
-
-    :raises UndetectableNameError: If the URL does not match any regexes
+    Raises:
+        UndetectableNameError: If the URL does not match any regexes
     """
     original_path = path
 
@@ -651,13 +659,15 @@ def parse_name_offset(path, v=None):
 def parse_name(path, ver=None):
     """Try to determine the name of a package from its filename or URL.
 
-    :param str path: The filename or URL for the package
-    :param str ver: The version of the package
+    Args:
+        path (str): The filename or URL for the package
+        ver (str): The version of the package
 
-    :return: The name of the package
-    :rtype: str
+    Returns:
+        str: The name of the package
 
-    :raises UndetectableNameError: If the URL does not match any regexes
+    Raises:
+        UndetectableNameError: If the URL does not match any regexes
     """
     name, start, length, i, regex = parse_name_offset(path, ver)
     return name
@@ -667,16 +677,17 @@ def parse_name_and_version(path):
     """Try to determine the name of a package and extract its version
     from its filename or URL.
 
-    :param str path: The filename or URL for the package
+    Args:
+        path (str): The filename or URL for the package
 
-    :return: A tuple containing:
-        The name of the package
-        The version of the package
+    Returns:
+        tuple of (str, Version)A tuple containing:
+            The name of the package
+            The version of the package
 
-    :rtype: tuple
-
-    :raises UndetectableVersionError: If the URL does not match any regexes
-    :raises UndetectableNameError: If the URL does not match any regexes
+    Raises:
+        UndetectableVersionError: If the URL does not match any regexes
+        UndetectableNameError: If the URL does not match any regexes
     """
     ver = parse_version(path)
     name = parse_name(path, ver)
@@ -804,9 +815,10 @@ def color_url(path, **kwargs):
        | Green:   Instances of version string from :func:`substitute_version`.
        | Magenta: Instances of the name (protected from substitution).
 
-    :param str path: The filename or URL for the package
-    :keyword bool errors: Append parse errors at end of string.
-    :keyword bool subs: Color substitutions as well as parsed name/version.
+    Args:
+        path (str): The filename or URL for the package
+        errors (bool): Append parse errors at end of string.
+        subs (bool): Color substitutions as well as parsed name/version.
     """
     errors = kwargs.get('errors', False)
     subs   = kwargs.get('subs', False)
diff --git a/lib/spack/spack/util/naming.py b/lib/spack/spack/util/naming.py
index cd35008aed..18142bd83f 100644
--- a/lib/spack/spack/util/naming.py
+++ b/lib/spack/spack/util/naming.py
@@ -110,13 +110,17 @@ def possible_spack_module_names(python_mod_name):
 
 
 def simplify_name(name):
-    """Simplifies a name which may include uppercase letters, periods,
+    """Simplify package name to only lowercase, digits, and dashes.
+
+    Simplifies a name which may include uppercase letters, periods,
     underscores, and pluses. In general, we want our package names to
     only contain lowercase letters, digits, and dashes.
 
-    :param str name: The original name of the package
-    :return: The new name of the package
-    :rtype: str
+    Args:
+        name (str): The original name of the package
+
+    Returns:
+        str: The new name of the package
     """
     # Convert CamelCase to Dashed-Names
     # e.g. ImageMagick -> Image-Magick
diff --git a/lib/spack/spack/util/pattern.py b/lib/spack/spack/util/pattern.py
index 7a1109f2d2..bebca1f419 100644
--- a/lib/spack/spack/util/pattern.py
+++ b/lib/spack/spack/util/pattern.py
@@ -28,20 +28,23 @@
 
 
 def composite(interface=None, method_list=None, container=list):
-    """Returns a class decorator that patches a class adding all the methods
-    it needs to be a composite for a given interface.
+    """Decorator implementing the GoF composite pattern.
 
-    :param interface: class exposing the interface to which the composite \
-        object must conform. Only non-private and non-special methods will \
-        be taken into account
+    Args:
+        interface (type): class exposing the interface to which the
+            composite object must conform. Only non-private and
+            non-special methods will be taken into account
+        method_list (list of str): names of methods that should be part
+            of the composite
+        container (MutableSequence): container for the composite object
+            (default = list).  Must fulfill the MutableSequence
+            contract. The composite class will expose the container API
+            to manage object composition
 
-    :param method_list: names of methods that should be part of the composite
+    Returns:
+        a class decorator that patches a class adding all the methods
+        it needs to be a composite for a given interface.
 
-    :param container: container for the composite object (default = list). \
-        Must fulfill the MutableSequence contract. The composite class will \
-        expose the container API to manage object composition
-
-    :return: class decorator
     """
     # Check if container fulfills the MutableSequence contract and raise an
     # exception if it doesn't. The patched class returned by the decorator will