API Docs: fix broken reference targets

57 files changed, 510 insertions, 471 deletions

diff --git a/lib/spack/docs/Makefile b/lib/spack/docs/Makefile
index 1a8c13e8fb..d86faa6ad4 100644
--- a/lib/spack/docs/Makefile
+++ b/lib/spack/docs/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
diff --git a/lib/spack/docs/build_systems/cmakepackage.rst b/lib/spack/docs/build_systems/cmakepackage.rst
index a3282514e8..3c3c96f92c 100644
--- a/lib/spack/docs/build_systems/cmakepackage.rst
+++ b/lib/spack/docs/build_systems/cmakepackage.rst
@@ -130,8 +130,8 @@ Adding flags to cmake
 To add additional flags to the ``cmake`` call, simply override the
 ``cmake_args`` function. The following example defines values for the flags
 ``WHATEVER``, ``ENABLE_BROKEN_FEATURE``, ``DETECT_HDF5``, and ``THREADS`` with
-and without the :py:meth:`~.CMakePackage.define` and
-:py:meth:`~.CMakePackage.define_from_variant` helper functions:
+and without the :meth:`~spack.build_systems.cmake.CMakePackage.define` and
+:meth:`~spack.build_systems.cmake.CMakePackage.define_from_variant` helper functions:
 
 .. code-block:: python
 
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 38d75747e3..20a1ba86c5 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -101,11 +101,14 @@ needs_sphinx = '1.8'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.graphviz',
-              'sphinx.ext.napoleon',
-              'sphinx.ext.todo',
-              'sphinxcontrib.programoutput']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinxcontrib.programoutput',
+]
 
 # Set default graphviz options
 graphviz_dot_args = [
@@ -164,6 +167,19 @@ gettext_uuid = False
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build', '_spack_root', '.spack-env']
 
+nitpicky = True
+nitpick_ignore = [
+    # Python classes that intersphinx is unable to resolve
+    ('py:class', 'argparse.HelpFormatter'),
+    ('py:class', 'contextlib.contextmanager'),
+    ('py:class', 'module'),
+    ('py:class', '_io.BufferedReader'),
+    ('py:class', 'unittest.case.TestCase'),
+    ('py:class', '_frozen_importlib_external.SourceFileLoader'),
+    # Spack classes that are private and we don't want to expose
+    ('py:class', 'spack.provider_index._IndexBase'),
+]
+
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
 
@@ -358,3 +374,11 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+
+# -- Extension configuration -------------------------------------------------
+
+# sphinx.ext.intersphinx
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst
index fe67b90950..31311e87f7 100644
--- a/lib/spack/docs/developer_guide.rst
+++ b/lib/spack/docs/developer_guide.rst
@@ -108,9 +108,9 @@ with a high level view of Spack's directory structure:
 
             spack/                <- spack module; contains Python code
                analyzers/         <- modules to run analysis on installed packages
-               build_systems/     <- modules for different build systems 
+               build_systems/     <- modules for different build systems
                cmd/               <- each file in here is a spack subcommand
-               compilers/         <- compiler description files          
+               compilers/         <- compiler description files
                container/         <- module for spack containerize
                hooks/             <- hook modules to run at different points
                modules/           <- modules for lmod, tcl, etc.
@@ -151,24 +151,22 @@ Package-related modules
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.package`
-  Contains the :class:`Package <spack.package.Package>` class, which
+  Contains the :class:`~spack.package.Package` class, which
   is the superclass for all packages in Spack.  Methods on ``Package``
   implement all phases of the :ref:`package lifecycle
   <package-lifecycle>` and manage the build process.
 
-:mod:`spack.packages`
-  Contains all of the packages in Spack and methods for managing them.
-  Functions like :func:`packages.get <spack.packages.get>` and
-  :func:`class_name_for_package_name
-  <packages.class_name_for_package_name>` handle mapping package module
-  names to class names and dynamically instantiating packages by name
-  from module files.
+:mod:`spack.util.naming`
+  Contains functions for mapping between Spack package names,
+  Python module names, and Python class names. Functions like
+  :func:`~spack.util.naming.mod_to_class` handle mapping package
+  module names to class names.
 
-:mod:`spack.relations`
-  *Relations* are relationships between packages, like
-  :func:`depends_on <spack.relations.depends_on>` and :func:`provides
-  <spack.relations.provides>`.  See :ref:`dependencies` and
-  :ref:`virtual-dependencies`.
+:mod:`spack.directives`
+  *Directives* are functions that can be called inside a package definition
+  to modify the package, like :func:`~spack.directives.depends_on`
+  and :func:`~spack.directives.provides`.  See :ref:`dependencies`
+  and :ref:`virtual-dependencies`.
 
 :mod:`spack.multimethod`
   Implementation of the :func:`@when <spack.multimethod.when>`
@@ -180,31 +178,27 @@ Spec-related modules
 ^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.spec`
-  Contains :class:`Spec <spack.spec.Spec>` and :class:`SpecParser
-  <spack.spec.SpecParser>`. Also implements most of the logic for
-  normalization and concretization of specs.
+  Contains :class:`~spack.spec.Spec` and :class:`~spack.spec.SpecParser`.
+  Also implements most of the logic for normalization and concretization
+  of specs.
 
 :mod:`spack.parse`
   Contains some base classes for implementing simple recursive descent
-  parsers: :class:`Parser <spack.parse.Parser>` and :class:`Lexer
-  <spack.parse.Lexer>`.  Used by :class:`SpecParser
-  <spack.spec.SpecParser>`.
+  parsers: :class:`~spack.parse.Parser` and :class:`~spack.parse.Lexer`.
+  Used by :class:`~spack.spec.SpecParser`.
 
 :mod:`spack.concretize`
-  Contains :class:`DefaultConcretizer
-  <spack.concretize.DefaultConcretizer>` implementation, which allows
-  site administrators to change Spack's :ref:`concretization-policies`.
+  Contains :class:`~spack.concretize.Concretizer` implementation,
+  which allows site administrators to change Spack's :ref:`concretization-policies`.
 
 :mod:`spack.version`
-  Implements a simple :class:`Version <spack.version.Version>` class
-  with simple comparison semantics.  Also implements
-  :class:`VersionRange <spack.version.VersionRange>` and
-  :class:`VersionList <spack.version.VersionList>`.  All three are
-  comparable with each other and offer union and intersection
-  operations.  Spack uses these classes to compare versions and to
-  manage version constraints on specs.  Comparison semantics are
-  similar to the ``LooseVersion`` class in ``distutils`` and to the
-  way RPM compares version strings.
+  Implements a simple :class:`~spack.version.Version` class with simple
+  comparison semantics.  Also implements :class:`~spack.version.VersionRange`
+  and :class:`~spack.version.VersionList`. All three are comparable with each
+  other and offer union and intersection operations. Spack uses these classes
+  to compare versions and to manage version constraints on specs. Comparison
+  semantics are similar to the ``LooseVersion`` class in ``distutils`` and to
+  the way RPM compares version strings.
 
 :mod:`spack.compilers`
   Submodules contains descriptors for all valid compilers in Spack.
@@ -232,7 +226,7 @@ Build environment
 :mod:`spack.stage`
   Handles creating temporary directories for builds.
 
-:mod:`spack.compilation`
+:mod:`spack.build_environment`
   This contains utility functions used by the compiler wrapper script,
   ``cc``.
 
@@ -257,22 +251,19 @@ Unit tests
   Implements Spack's test suite.  Add a module and put its name in
   the test suite in ``__init__.py`` to add more unit tests.
 
-:mod:`spack.test.mock_packages`
-  This is a fake package hierarchy used to mock up packages for
-  Spack's test suite.
-
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Research and Monitoring Modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.monitor`
-  Contains :class:`SpackMonitor <spack.monitor.SpackMonitor>`. This is accessed
-  from the ``spack install`` and ``spack analyze`` commands to send build
-  and package metadada up to a `Spack Monitor <https://github.com/spack/spack-monitor>`_ server. 
+  Contains :class:`~spack.monitor.SpackMonitorClient`. This is accessed from
+  the ``spack install`` and ``spack analyze`` commands to send build and
+  package metadata up to a `Spack Monitor
+  <https://github.com/spack/spack-monitor>`_ server.
 
 
 :mod:`spack.analyzers`
-  A module folder with a :class:`AnalyzerBase <spack.analyzers.analyzer_base.AnalyzerBase>`
+  A module folder with a :class:`~spack.analyzers.analyzer_base.AnalyzerBase`
   that provides base functions to run, save, and (optionally) upload analysis
   results to a `Spack Monitor <https://github.com/spack/spack-monitor>`_ server.
 
@@ -286,7 +277,7 @@ Other Modules
   tarball URLs.
 
 :mod:`spack.error`
-  :class:`SpackError <spack.error.SpackError>`, the base class for
+  :class:`~spack.error.SpackError`, the base class for
   Spack's exception hierarchy.
 
 :mod:`llnl.util.tty`
@@ -335,8 +326,8 @@ Writing analyzers
 To write an analyzer, you should add a new python file to the
 analyzers module directory at ``lib/spack/spack/analyzers`` .
 Your analyzer should be a subclass of the :class:`AnalyzerBase <spack.analyzers.analyzer_base.AnalyzerBase>`. For example, if you want
-to add an analyzer class ``Myanalyzer`` you woul write to 
-``spack/analyzers/myanalyzer.py`` and import and 
+to add an analyzer class ``Myanalyzer`` you would write to
+``spack/analyzers/myanalyzer.py`` and import and
 use the base as follows:
 
 .. code-block:: python
@@ -347,7 +338,7 @@ use the base as follows:
 
 
 Note that the class name is your module file name, all lowercase
-except for the first capital letter. You can  look at other analyzers in 
+except for the first capital letter. You can  look at other analyzers in
 that analyzer directory for examples. The guide here will tell you about the basic functions needed.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -356,13 +347,13 @@ Analyzer Output Directory
 
 By default, when you run ``spack analyze run`` an analyzer output directory will
 be created in your spack user directory in your ``$HOME``. The reason we output here
-is because the install directory might not always be writable. 
+is because the install directory might not always be writable.
 
 .. code-block:: console
 
     ~/.spack/
       analyzers
-      
+
 Result files will be written here, organized in subfolders in the same structure
 as the package, with each analyzer owning it's own subfolder. for example:
 
@@ -380,11 +371,11 @@ as the package, with each analyzer owning it's own subfolder. for example:
                 │   └── spack-analyzer-install-files.json
                 └── libabigail
                     └── lib
-                        └── spack-analyzer-libabigail-libz.so.1.2.11.xml 
+                        └── spack-analyzer-libabigail-libz.so.1.2.11.xml
 
 
 Notice that for the libabigail analyzer, since results are generated per object,
-we honor the object's folder in case there are equivalently named files in 
+we honor the object's folder in case there are equivalently named files in
 different folders. The result files are typically written as json so they can be easily read and  uploaded in a future interaction with a monitor.
 
 
@@ -426,7 +417,7 @@ and then return the object with a key as the analyzer name. The result data
 should be a list of objects, each with a name, ``analyzer_name``, ``install_file``,
 and one of ``value`` or ``binary_value``. The install file should be for a relative
 path, and not the absolute path. For example, let's say we extract a metric called
-``metric`` for ``bin/wget`` using our analyzer ``thebest-analyzer``. 
+``metric`` for ``bin/wget`` using our analyzer ``thebest-analyzer``.
 We might have data that looks like this:
 
 .. code-block:: python
@@ -482,7 +473,7 @@ Saving Analyzer Results
 The analyzer will have ``save_result`` called, with the result object generated
 to save it to the filesystem, and if the user has added the ``--monitor`` flag
 to upload it to a monitor server. If your result follows an accepted result
-format and you don't need to parse it further, you don't need to add this 
+format and you don't need to parse it further, you don't need to add this
 function to your class. However, if your result data is large or otherwise
 needs additional parsing, you can define it. If you define the function, it
 is useful to know about the ``output_dir`` property, which you can join
@@ -548,7 +539,7 @@ each one (separately) to the monitor:
 
 Notice that this function, if you define it, requires a result object (generated by
 ``run()``, a monitor (if you want to send), and a boolean ``overwrite`` to be used
-to check if a result exists first, and not write to it if the result exists and 
+to check if a result exists first, and not write to it if the result exists and
 overwrite is False. Also notice that since we already saved these files to the analyzer metadata folder, we return early if a monitor isn't defined, because this function serves to send  results to the monitor. If you haven't saved anything to the analyzer metadata folder
 yet, you might want to do that here. You should also use ``tty.info`` to give
 the user a message of "Writing result to $DIRNAME."
@@ -616,7 +607,7 @@ types of hooks in the ``__init__.py``, and then python files in that folder
 can use hook functions. The files are automatically parsed, so if you write
 a new file for some integration (e.g., ``lib/spack/spack/hooks/myintegration.py``
 you can then write hook functions in that file that will be automatically detected,
-and run whenever your hook is called. This section will cover the basic kind 
+and run whenever your hook is called. This section will cover the basic kind
 of hooks, and how to write them.
 
 ^^^^^^^^^^^^^^
@@ -624,7 +615,7 @@ Types of Hooks
 ^^^^^^^^^^^^^^
 
 The following hooks are currently implemented to make it easy for you,
-the developer, to add hooks at different stages of a spack install or similar. 
+the developer, to add hooks at different stages of a spack install or similar.
 If there is a hook that you would like and is missing, you can propose to add a new one.
 
 """""""""""""""""""""
@@ -632,9 +623,9 @@ If there is a hook that you would like and is missing, you can propose to add a
 """""""""""""""""""""
 
 A ``pre_install`` hook is run within an install subprocess, directly before
-the install starts. It expects a single argument of a spec, and is run in 
+the install starts. It expects a single argument of a spec, and is run in
 a multiprocessing subprocess. Note that if you see ``pre_install`` functions associated with packages these are not hooks
-as we have defined them here, but rather callback functions associated with 
+as we have defined them here, but rather callback functions associated with
 a package install.
 
 
@@ -657,7 +648,7 @@ here.
 This hook is run at the beginning of ``lib/spack/spack/installer.py``,
 in the install function of a ``PackageInstaller``,
 and importantly is not part of a build process, but before it. This is when
-we have just newly grabbed the task, and are preparing to install. If you 
+we have just newly grabbed the task, and are preparing to install. If you
 write a hook of this type, you should provide the spec to it.
 
 .. code-block:: python
@@ -666,7 +657,7 @@ write a hook of this type, you should provide the spec to it.
         """On start of an install, we want to...
         """
         print('on_install_start')
-    
+
 
 """"""""""""""""""""""""""""
 ``on_install_success(spec)``
@@ -744,8 +735,8 @@ to trigger after anything is written to a logger. You would add it as follows:
     post_install = HookRunner('post_install')
 
     # hooks related to logging
-    post_log_write = HookRunner('post_log_write') # <- here is my new hook! 
-    
+    post_log_write = HookRunner('post_log_write') # <- here is my new hook!
+
 
 You then need to decide what arguments my hook would expect. Since this is
 related to logging, let's say that you want a message and level. That means
@@ -775,7 +766,7 @@ In this example, we use it outside of a logger that is already defined:
 
 This is not to say that this would be the best way to implement an integration
 with the logger (you'd probably want to write a custom logger, or you could
-have the hook defined within the logger) but serves as an example of writing a hook. 
+have the hook defined within the logger) but serves as an example of writing a hook.
 
 ----------
 Unit tests
@@ -905,7 +896,7 @@ just like you would with the normal ``python`` command.
 ^^^^^^^^^^^^^^^
 
 Spack blame is a way to quickly see contributors to packages or files
-in the spack repository. You should provide a target package name or 
+in the spack repository. You should provide a target package name or
 file name to the command. Here is an example asking to see contributions
 for the package "python":
 
@@ -915,8 +906,8 @@ for the package "python":
     LAST_COMMIT  LINES  %      AUTHOR            EMAIL
     2 weeks ago  3      0.3    Mickey Mouse   <cheddar@gmouse.org>
     a month ago  927    99.7   Minnie Mouse   <swiss@mouse.org>
-                                        
-    2 weeks ago  930    100.0  
+
+    2 weeks ago  930    100.0
 
 
 By default, you will get a table view (shown above) sorted by date of contribution,
@@ -1287,7 +1278,7 @@ Publishing a release on GitHub
 
 #. Create the release in GitHub.
 
-   * Go to 
+   * Go to
      `github.com/spack/spack/releases <https://github.com/spack/spack/releases>`_
      and click ``Draft a new release``.
 
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 59dad4f966..6616d2a331 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -2884,52 +2884,52 @@ The package base class, usually specialized for a given build system, determines
 actual set of entities available for overriding.
 The classes that are currently provided by Spack are:
 
-    +-------------------------------+----------------------------------+
-    |        **Base Class**         |           **Purpose**            |
-    +===============================+==================================+
-    | :py:class:`.Package`          | General base class not           |
-    |                               | specialized for any build system |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.MakefilePackage`  | Specialized class for packages   |
-    |                               | built invoking                   |
-    |                               | hand-written Makefiles           |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.AutotoolsPackage` | Specialized class for packages   |
-    |                               | built using GNU Autotools        |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.CMakePackage`     | Specialized class for packages   |
-    |                               | built using CMake                |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.CudaPackage`      | A helper class for packages that |
-    |                               | use CUDA                         |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.QMakePackage`     | Specialized class for packages   |
-    |                               | build using QMake                |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.ROCmPackage`      | A helper class for packages that |
-    |                               | use ROCm                         |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.SConsPackage`     | Specialized class for packages   |
-    |                               | built using SCons                |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.WafPackage`       | Specialized class for packages   |
-    |                               | built using Waf                  |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.RPackage`         | Specialized class for            |
-    |                               | :py:class:`.R` extensions        |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.OctavePackage`    | Specialized class for            |
-    |                               | :py:class:`.Octave` packages     |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.PythonPackage`    | Specialized class for            |
-    |                               | :py:class:`.Python` extensions   |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.PerlPackage`      | Specialized class for            |
-    |                               | :py:class:`.Perl` extensions     |
-    +-------------------------------+----------------------------------+
-    | :py:class:`.IntelPackage`     | Specialized class for licensed   |
-    |                               | Intel software                   |
-    +-------------------------------+----------------------------------+
++-------------------------=--------------------------------+----------------------------------+
+|     **Base Class**                                       |           **Purpose**            |
++==========================================================+==================================+
+| :class:`~spack.package.Package`                          | General base class not           |
+|                                                          | specialized for any build system |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.makefile.MakefilePackage`   | Specialized class for packages   |
+|                                                          | built invoking                   |
+|                                                          | hand-written Makefiles           |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.autotools.AutotoolsPackage` | Specialized class for packages   |
+|                                                          | built using GNU Autotools        |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.cmake.CMakePackage`         | Specialized class for packages   |
+|                                                          | built using CMake                |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.cuda.CudaPackage`           | A helper class for packages that |
+|                                                          | use CUDA                         |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.qmake.QMakePackage`         | Specialized class for packages   |
+|                                                          | built using QMake                |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.rocm.ROCmPackage`           | A helper class for packages that |
+|                                                          | use ROCm                         |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.scons.SConsPackage`         | Specialized class for packages   |
+|                                                          | built using SCons                |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.waf.WafPackage`             | Specialized class for packages   |
+|                                                          | built using Waf                  |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.r.RPackage`                 | Specialized class for            |
+|                                                          | R extensions                     |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.octave.OctavePackage`       | Specialized class for            |
+|                                                          | Octave packages                  |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.python.PythonPackage`       | Specialized class for            |
+|                                                          | Python extensions                |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.perl.PerlPackage`           | Specialized class for            |
+|                                                          | Perl extensions                  |
++----------------------------------------------------------+----------------------------------+
+| :class:`~spack.build_systems.intel.IntelPackage`         | Specialized class for licensed   |
+|                                                          | Intel software                   |
++----------------------------------------------------------+----------------------------------+
 
 
 .. note::
@@ -2939,7 +2939,7 @@ The classes that are currently provided by Spack are:
         rare cases where manual intervention is needed we need to stress that a
         package base class depends on the *build system* being used, not the language of the package.
         For example, a Python extension installed with CMake would ``extends('python')`` and
-        subclass from :py:class:`.CMakePackage`.
+        subclass from :class:`~spack.build_systems.cmake.CMakePackage`.
 
 ^^^^^^^^^^^^^^^^^^^^^
 Installation pipeline
@@ -4079,7 +4079,7 @@ prefix **before** ``make install``. Builds like this can falsely report
 success when an error occurs before the installation is complete. Simple
 sanity checks can be used to identify files and or directories that are
 required of a successful installation. Spack checks for the presence of
-the files and directories after ``install()`` runs. 
+the files and directories after ``install()`` runs.
 
 If any of the listed files or directories are missing, then the build will
 fail and the install prefix will be removed. If they all exist, then Spack
@@ -4193,7 +4193,7 @@ need to use two decorators for each phase test method:
 The first decorator tells Spack when in the installation process to
 run your test method installation process; namely *after* the provided
 installation phase. The second decorator tells Spack to only run the
-checks when the ``--test`` option is provided on the command line. 
+checks when the ``--test`` option is provided on the command line.
 
 .. note::
 
@@ -4267,17 +4267,17 @@ tests can be performed days, even weeks, after the software is installed.
 
 Stand-alone tests are checks that should run relatively quickly -- as
 in on the order of at most a few minutes -- and ideally execute all
-aspects of the installed software, or at least key functionality. 
+aspects of the installed software, or at least key functionality.
 
 .. note::
 
     Execution speed is important because these tests are intended
     to quickly assess whether the installed software works on the
     system.
-    
+
     Failing stand-alone tests indicate that there is no reason to
     proceed with more resource-intensive tests.
-    
+
     Passing stand-alone (or smoke) tests can lead to more thorough
     testing, such as extensive unit or regression tests, or tests
     that run at scale. Spack support for more thorough testing is
@@ -4307,7 +4307,7 @@ file such that:
      test_stage: /path/to/stage
 
 The package can access this path **during test processing** using
-`self.test_suite.stage`. 
+`self.test_suite.stage`.
 
 .. note::
 
@@ -4388,7 +4388,7 @@ can be implemented as shown below.
        @run_after('install')
        def copy_test_sources(self):
            srcs = ['tests',
-                   join_path('examples', 'foo.c'), 
+                   join_path('examples', 'foo.c'),
                    join_path('examples', 'bar.c')]
            self.cache_extra_test_sources(srcs)
 
@@ -4446,7 +4446,7 @@ Examples include:
 - expected test output
 
 These extra files should be added to the ``test`` subdirectory of the
-package in the Spack repository. 
+package in the Spack repository.
 
 Spack will **automatically copy** the contents of that directory to the
 test staging directory for stand-alone testing. The ``test`` method can
@@ -4471,7 +4471,7 @@ The signature for ``get_escaped_text_output`` is:
 
 where ``filename`` is the path to the file containing the expected output.
 
-The ``filename`` for a :ref:`custom file <cache_custom_files>` can be 
+The ``filename`` for a :ref:`custom file <cache_custom_files>` can be
 accessed and used as illustrated by a simplified version of an ``sqlite``
 package check:
 
@@ -4591,10 +4591,10 @@ where each argument has the following meaning:
 
   Options are a list of strings to be passed to the executable when
   it runs.
-  
+
   The default is ``[]``, which means no options are provided to the
   executable.
- 
+
 * ``expected`` is an optional list of expected output strings.
 
   Spack requires every string in ``expected`` to be a regex matching
@@ -4605,31 +4605,31 @@ where each argument has the following meaning:
 
   The expected output can be :ref:`read from a file
   <expected_test_output_from_file>`.
-  
+
   The default is ``expected=[]``, so Spack will not check the output.
- 
+
 * ``status`` is the optional expected return code(s).
 
   A list of return codes corresponding to successful execution can
   be provided (e.g., ``status=[0,3,7]``). Support for non-zero return
   codes allows for basic **expected failure** tests as well as different
   return codes across versions of the software.
-  
+
   The default is ``status=[0]``, which corresponds to **successful**
   execution in the sense that the executable does not exit with a
   failure code or raise an exception.
- 
+
 * ``installed`` is used to require ``exe`` to be within the package
   prefix.
-  
+
   If ``True``, then the path for ``exe`` is required to be within the
   package prefix; otherwise, the path is not constrained.
-  
+
   The default is ``False``, so the fully qualified path for ``exe``
   does **not** need to be within the installation directory.
- 
+
 * ``purpose`` is an optional heading describing the the test part.
- 
+
   Output from the test is written to a test log file so this argument
   serves as a searchable heading in text logs to highlight the start
   of the test part. Having a description can be helpful when debugging
@@ -4644,10 +4644,10 @@ where each argument has the following meaning:
 
   The default is ``False``, which means the test executable must be
   present for any installable version of the software.
- 
+
 * ``work_dir`` is the path to the directory from which the executable
   will run.
-  
+
   The default of ``None`` corresponds to the current directory (``'.'``).
 
 """""""""""""""""""""""""""""""""""""""""
@@ -4754,7 +4754,7 @@ where only the outputs for the first of each set are shown:
    Copyright (C) 2018 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-   
+
    PASSED
    ...
    ==> [2021-04-26-17:35:20.493921] test: checking mpirun output
@@ -4915,7 +4915,7 @@ This is already part of the boilerplate for packages created with
 Filtering functions
 ^^^^^^^^^^^^^^^^^^^
 
-:py:func:`filter_file(regex, repl, *filenames, **kwargs) <spack.filter_file>`
+:py:func:`filter_file(regex, repl, *filenames, **kwargs) <llnl.util.filesystem.filter_file>`
   Works like ``sed`` but with Python regular expression syntax.  Takes
   a regular expression, a replacement, and a set of files.  ``repl``
   can be a raw string or a callable function.  If it is a raw string,
@@ -4953,7 +4953,7 @@ Filtering functions
         filter_file('CXX="c++"', 'CXX="%s"' % self.compiler.cxx,
                     prefix.bin.mpicxx)
 
-:py:func:`change_sed_delimiter(old_delim, new_delim, *filenames) <spack.change_sed_delim>`
+:py:func:`change_sed_delimiter(old_delim, new_delim, *filenames) <llnl.util.filesystem.change_sed_delimiter>`
     Some packages, like TAU, have a build system that can't install
     into directories with, e.g. '@' in the name, because they use
     hard-coded ``sed`` commands in their build.
@@ -4975,14 +4975,14 @@ Filtering functions
 File functions
 ^^^^^^^^^^^^^^
 
-:py:func:`ancestor(dir, n=1) <spack.ancestor>`
+:py:func:`ancestor(dir, n=1) <llnl.util.filesystem.ancestor>`
   Get the n\ :sup:`th` ancestor of the directory ``dir``.
 
-:py:func:`can_access(path) <spack.can_access>`
+:py:func:`can_access(path) <llnl.util.filesystem.can_access>`
   True if we can read and write to the file at ``path``.  Same as
   native python ``os.access(file_name, os.R_OK|os.W_OK)``.
 
-:py:func:`install(src, dest) <spack.install>`
+:py:func:`install(src, dest) <llnl.util.filesystem.install>`
   Install a file to a particular location.  For example, install a
   header into the ``include`` directory under the install ``prefix``:
 
@@ -4990,14 +4990,14 @@ File functions
 
      install('my-header.h', prefix.include)
 
-:py:func:`join_path(*paths) <spack.join_path>`
+:py:func:`join_path(*paths) <llnl.util.filesystem.join_path>`
   An alias for ``os.path.join``. This joins paths using the OS path separator.
 
-:py:func:`mkdirp(*paths) <spack.mkdirp>`
+:py:func:`mkdirp(*paths) <llnl.util.filesystem.mkdirp>`
   Create each of the directories in ``paths``, creating any parent
   directories if they do not exist.
 
-:py:func:`working_dir(dirname, kwargs) <spack.working_dir>`
+:py:func:`working_dir(dirname, kwargs) <llnl.util.filesystem.working_dir>`
   This is a Python `Context Manager
   <https://docs.python.org/2/library/contextlib.html>`_ that makes it
   easier to work with subdirectories in builds.  You use this with the
@@ -5039,7 +5039,7 @@ File functions
      The ``create=True`` keyword argument causes the command to create
      the directory if it does not exist.
 
-:py:func:`touch(path) <spack.touch>`
+:py:func:`touch(path) <llnl.util.filesystem.touch>`
   Create an empty file at ``path``.
 
 .. _make-package-findable:
diff --git a/lib/spack/llnl/util/argparsewriter.py b/lib/spack/llnl/util/argparsewriter.py
index 6d44713e39..1ba5bd5c37 100644
--- a/lib/spack/llnl/util/argparsewriter.py
+++ b/lib/spack/llnl/util/argparsewriter.py
@@ -326,7 +326,7 @@ class ArgparseCompletionWriter(ArgparseWriter):
         """Returns the syntax needed to end a function definition.
 
         Parameters:
-            prog (str, optional): the command name
+            prog (str or None): the command name
 
         Returns:
             str: the function definition ending
diff --git a/lib/spack/llnl/util/filesystem.py b/lib/spack/llnl/util/filesystem.py
index 0ebc35a040..3cf6553165 100644
--- a/lib/spack/llnl/util/filesystem.py
+++ b/lib/spack/llnl/util/filesystem.py
@@ -444,7 +444,7 @@ def copy_tree(src, dest, symlinks=True, ignore=None, _permissions=False):
         src (str): the directory to copy
         dest (str): the destination directory
         symlinks (bool): whether or not to preserve symlinks
-        ignore (function): function indicating which files to ignore
+        ignore (typing.Callable): function indicating which files to ignore
         _permissions (bool): for internal use only
 
     Raises:
@@ -518,7 +518,7 @@ def install_tree(src, dest, symlinks=True, ignore=None):
         src (str): the directory to install
         dest (str): the destination directory
         symlinks (bool): whether or not to preserve symlinks
-        ignore (function): function indicating which files to ignore
+        ignore (typing.Callable): function indicating which files to ignore
 
     Raises:
         IOError: if *src* does not match any files or directories
@@ -557,12 +557,12 @@ def mkdirp(*paths, **kwargs):
         paths (str): paths to create with mkdirp
 
     Keyword Aguments:
-        mode (permission bits or None, optional): optional permissions to set
+        mode (permission bits or None): optional permissions to set
             on the created directory -- use OS default if not provided
-        group (group name or None, optional): optional group for permissions of
+        group (group name or None): optional group for permissions of
             final created directory -- use OS default if not provided. Only
             used if world write permissions are not set
-        default_perms ('parents' or 'args', optional): The default permissions
+        default_perms (str or None): one of 'parents' or 'args'. The default permissions
             that are set for directories that are not themselves an argument
             for mkdirp. 'parents' means intermediate directories get the
             permissions of their direct parent directory, 'args' means
@@ -866,7 +866,7 @@ def traverse_tree(source_root, dest_root, rel_path='', **kwargs):
     Keyword Arguments:
         order (str): Whether to do pre- or post-order traversal. Accepted
             values are 'pre' and 'post'
-        ignore (function): function indicating which files to ignore
+        ignore (typing.Callable): function indicating which files to ignore
         follow_nonexisting (bool): Whether to descend into directories in
             ``src`` that do not exit in ``dest``. Default is True
         follow_links (bool): Whether to descend into symlinks in ``src``
@@ -1114,11 +1114,11 @@ def find(root, files, recursive=True):
     Parameters:
         root (str): The root directory to start searching from
         files (str or Sequence): Library name(s) to search for
-        recurse (bool, optional): if False search only root folder,
+        recursive (bool): if False search only root folder,
             if True descends top-down from the root. Defaults to True.
 
     Returns:
-        list of strings: The files that have been found
+        list: The files that have been found
     """
     if isinstance(files, six.string_types):
         files = [files]
@@ -1200,7 +1200,7 @@ class FileList(Sequence):
         ['/dir1', '/dir2']
 
         Returns:
-            list of strings: A list of directories
+            list: A list of directories
         """
         return list(dedupe(
             os.path.dirname(x) for x in self.files if os.path.dirname(x)
@@ -1218,7 +1218,7 @@ class FileList(Sequence):
         ['a.h', 'b.h']
 
         Returns:
-            list of strings: A list of base-names
+            list: A list of base-names
         """
         return list(dedupe(os.path.basename(x) for x in self.files))
 
@@ -1305,7 +1305,7 @@ class HeaderList(FileList):
         """Stable de-duplication of the headers.
 
         Returns:
-            list of strings: A list of header files
+            list: A list of header files
         """
         return self.files
 
@@ -1318,7 +1318,7 @@ class HeaderList(FileList):
         ['a', 'b']
 
         Returns:
-            list of strings: A list of files without extensions
+            list: A list of files without extensions
         """
         names = []
 
@@ -1409,9 +1409,9 @@ def find_headers(headers, root, recursive=False):
     =======  ====================================
 
     Parameters:
-        headers (str or list of str): Header name(s) to search for
+        headers (str or list): Header name(s) to search for
         root (str): The root directory to start searching from
-        recursive (bool, optional): if False search only root folder,
+        recursive (bool): if False search only root folder,
             if True descends top-down from the root. Defaults to False.
 
     Returns:
@@ -1447,7 +1447,7 @@ def find_all_headers(root):
     in the directory passed as argument.
 
     Args:
-        root (path): directory where to look recursively for header files
+        root (str): directory where to look recursively for header files
 
     Returns:
         List of all headers found in ``root`` and subdirectories.
@@ -1467,7 +1467,7 @@ class LibraryList(FileList):
         """Stable de-duplication of library files.
 
         Returns:
-            list of strings: A list of library files
+            list: A list of library files
         """
         return self.files
 
@@ -1480,7 +1480,7 @@ class LibraryList(FileList):
         ['a', 'b']
 
         Returns:
-            list of strings: A list of library names
+            list: A list of library names
         """
         names = []
 
@@ -1565,8 +1565,8 @@ def find_system_libraries(libraries, shared=True):
     =======  ====================================
 
     Parameters:
-        libraries (str or list of str): Library name(s) to search for
-        shared (bool, optional): if True searches for shared libraries,
+        libraries (str or list): Library name(s) to search for
+        shared (bool): if True searches for shared libraries,
             otherwise for static. Defaults to True.
 
     Returns:
@@ -1616,11 +1616,11 @@ def find_libraries(libraries, root, shared=True, recursive=False):
     =======  ====================================
 
     Parameters:
-        libraries (str or list of str): Library name(s) to search for
+        libraries (str or list): Library name(s) to search for
         root (str): The root directory to start searching from
-        shared (bool, optional): if True searches for shared libraries,
+        shared (bool): if True searches for shared libraries,
             otherwise for static. Defaults to True.
-        recursive (bool, optional): if False search only root folder,
+        recursive (bool): if False search only root folder,
             if True descends top-down from the root. Defaults to False.
 
     Returns:
diff --git a/lib/spack/llnl/util/lang.py b/lib/spack/llnl/util/lang.py
index 00b0490600..3e81a34422 100644
--- a/lib/spack/llnl/util/lang.py
+++ b/lib/spack/llnl/util/lang.py
@@ -573,8 +573,8 @@ def pretty_date(time, now=None):
     """Convert a datetime or timestamp to a pretty, relative date.
 
     Args:
-        time (datetime or int): date to print prettily
-        now (datetime): dateimte for 'now', i.e. the date the pretty date
+        time (datetime.datetime or int): date to print prettily
+        now (datetime.datetime): datetime for 'now', i.e. the date the pretty date
             is relative to (default is datetime.now())
 
     Returns:
@@ -648,7 +648,7 @@ def pretty_string_to_date(date_str, now=None):
             or be a *pretty date* (like ``yesterday`` or ``two months ago``)
 
     Returns:
-        (datetime): datetime object corresponding to ``date_str``
+        (datetime.datetime): datetime object corresponding to ``date_str``
     """
 
     pattern = {}
diff --git a/lib/spack/llnl/util/lock.py b/lib/spack/llnl/util/lock.py
index cd390693c4..0c0cc7f634 100644
--- a/lib/spack/llnl/util/lock.py
+++ b/lib/spack/llnl/util/lock.py
@@ -14,9 +14,19 @@ import llnl.util.tty as tty
 
 import spack.util.string
 
-__all__ = ['Lock', 'LockTransaction', 'WriteTransaction', 'ReadTransaction',
-           'LockError', 'LockTimeoutError',
-           'LockPermissionError', 'LockROFileError', 'CantCreateLockError']
+__all__ = [
+    'Lock',
+    'LockDowngradeError',
+    'LockUpgradeError',
+    'LockTransaction',
+    'WriteTransaction',
+    'ReadTransaction',
+    'LockError',
+    'LockTimeoutError',
+    'LockPermissionError',
+    'LockROFileError',
+    'CantCreateLockError'
+]
 
 #: Mapping of supported locks to description
 lock_type = {fcntl.LOCK_SH: 'read', fcntl.LOCK_EX: 'write'}
@@ -401,7 +411,7 @@ class Lock(object):
         """Releases a read lock.
 
         Arguments:
-            release_fn (callable): function to call *before* the last recursive
+            release_fn (typing.Callable): function to call *before* the last recursive
                 lock (read or write) is released.
 
         If the last recursive lock will be released, then this will call
@@ -437,7 +447,7 @@ class Lock(object):
         """Releases a write lock.
 
         Arguments:
-            release_fn (callable): function to call before the last recursive
+            release_fn (typing.Callable): function to call before the last recursive
                 write is released.
 
         If the last recursive *write* lock will be released, then this
@@ -533,10 +543,10 @@ class LockTransaction(object):
     Arguments:
         lock (Lock): underlying lock for this transaction to be accquired on
             enter and released on exit
-        acquire (callable or contextmanager): function to be called after lock
-            is acquired, or contextmanager to enter after acquire and leave
+        acquire (typing.Callable or contextlib.contextmanager): function to be called
+            after lock is acquired, or contextmanager to enter after acquire and leave
             before release.
-        release (callable): function to be called before release. If
+        release (typing.Callable): function to be called before release. If
             ``acquire`` is a contextmanager, this will be called *after*
             exiting the nexted context and before the lock is released.
         timeout (float): number of seconds to set for the timeout when
diff --git a/lib/spack/llnl/util/tty/colify.py b/lib/spack/llnl/util/tty/colify.py
index ca157e3303..22b824ac0c 100644
--- a/lib/spack/llnl/util/tty/colify.py
+++ b/lib/spack/llnl/util/tty/colify.py
@@ -109,19 +109,17 @@ def colify(elts, **options):
     using ``str()``.
 
     Keyword Arguments:
-        output (stream): A file object to write to. Default is ``sys.stdout``
-        indent (int):    Optionally indent all columns by some number of spaces
-        padding (int):   Spaces between columns. Default is 2
-        width (int):     Width of the output. Default is 80 if tty not detected
-        cols (int):      Force number of columns. Default is to size to
-                         terminal, or single-column if no tty
-        tty (bool):      Whether to attempt to write to a tty. Default is to
-                         autodetect a tty. Set to False to force single-column
-                         output
-        method (str):    Method to use to fit columns. Options are variable or
-                         uniform. Variable-width columns are tighter, uniform
-                         columns are all the same width and fit less data on
-                         the screen
+        output (typing.IO): A file object to write to. Default is ``sys.stdout``
+        indent (int): Optionally indent all columns by some number of spaces
+        padding (int): Spaces between columns. Default is 2
+        width (int): Width of the output. Default is 80 if tty not detected
+        cols (int): Force number of columns. Default is to size to terminal, or
+            single-column if no tty
+        tty (bool): Whether to attempt to write to a tty. Default is to autodetect a
+            tty. Set to False to force single-column output
+        method (str): Method to use to fit columns. Options are variable or uniform.
+            Variable-width columns are tighter, uniform columns are all the same width
+            and fit less data on the screen
     """
     # Get keyword arguments or set defaults
     cols         = options.pop("cols", 0)
diff --git a/lib/spack/spack/architecture.py b/lib/spack/spack/architecture.py
index 951109c892..17fbc0e2f1 100644
--- a/lib/spack/spack/architecture.py
+++ b/lib/spack/spack/architecture.py
@@ -193,8 +193,8 @@ class Target(object):
         the compiler passed as argument.
 
         Args:
-            compiler (CompilerSpec or Compiler): object that contains both the
-                name and the version of the compiler we want to use
+            compiler (spack.spec.CompilerSpec or spack.compiler.Compiler): object that
+                contains both the name and the version of the compiler we want to use
         """
         # Mixed toolchains are not supported yet
         import spack.compilers
diff --git a/lib/spack/spack/binary_distribution.py b/lib/spack/spack/binary_distribution.py
index 31ac93cffe..647b71cfe3 100644
--- a/lib/spack/spack/binary_distribution.py
+++ b/lib/spack/spack/binary_distribution.py
@@ -206,7 +206,7 @@ class BinaryCacheIndex(object):
         The cache can be updated by calling ``update()`` on the cache.
 
         Args:
-            spec (Spec): Concrete spec to find
+            spec (spack.spec.Spec): Concrete spec to find
 
         Returns:
             An list of objects containing the found specs and mirror url where
@@ -1079,14 +1079,14 @@ def download_tarball(spec, preferred_mirrors=None):
     path to downloaded tarball if successful, None otherwise.
 
     Args:
-        spec (Spec): Concrete spec
+        spec (spack.spec.Spec): Concrete spec
         preferred_mirrors (list): If provided, this is a list of preferred
-        mirror urls.  Other configured mirrors will only be used if the
-        tarball can't be retrieved from one of these.
+            mirror urls.  Other configured mirrors will only be used if the
+            tarball can't be retrieved from one of these.
 
     Returns:
         Path to the downloaded tarball, or ``None`` if the tarball could not
-            be downloaded from any configured mirrors.
+        be downloaded from any configured mirrors.
     """
     if not spack.mirror.MirrorCollection():
         tty.die("Please add a spack mirror to allow " +
@@ -1455,7 +1455,7 @@ def get_mirrors_for_spec(spec=None, full_hash_match=False,
     indicating the mirrors on which it can be found
 
     Args:
-        spec (Spec): The spec to look for in binary mirrors
+        spec (spack.spec.Spec): The spec to look for in binary mirrors
         full_hash_match (bool): If True, only includes mirrors where the spec
             full hash matches the locally computed full hash of the ``spec``
             argument.  If False, any mirror which has a matching DAG hash
@@ -1732,11 +1732,11 @@ def check_specs_against_mirrors(mirrors, specs, output_file=None,
 
     Arguments:
         mirrors (dict): Mirrors to check against
-        specs (iterable): Specs to check against mirrors
-        output_file (string): Path to output file to be written.  If provided,
+        specs (typing.Iterable): Specs to check against mirrors
+        output_file (str): Path to output file to be written.  If provided,
             mirrors with missing or out-of-date specs will be formatted as a
             JSON object and written to this file.
-        rebuild_on_errors (boolean): Treat any errors encountered while
+        rebuild_on_errors (bool): Treat any errors encountered while
             checking specs as a signal to rebuild package.
 
     Returns: 1 if any spec was out-of-date on any mirror, 0 otherwise.
diff --git a/lib/spack/spack/bootstrap.py b/lib/spack/spack/bootstrap.py
index 896c1cad4e..af12f095f7 100644
--- a/lib/spack/spack/bootstrap.py
+++ b/lib/spack/spack/bootstrap.py
@@ -134,7 +134,7 @@ def get_executable(exe, spec=None, install=False):
 
     Args:
         exe (str): needed executable name
-        spec (Spec or str): spec to search for exe in (default exe)
+        spec (spack.spec.Spec or str): spec to search for exe in (default exe)
         install (bool): install spec if not available
 
     When ``install`` is True, Spack will use the python used to run Spack as an
diff --git a/lib/spack/spack/build_environment.py b/lib/spack/spack/build_environment.py
index c9be0bc1d8..7e99dc6441 100644
--- a/lib/spack/spack/build_environment.py
+++ b/lib/spack/spack/build_environment.py
@@ -455,11 +455,11 @@ def determine_number_of_jobs(
     cap to the number of CPUs available to avoid oversubscription.
 
     Parameters:
-        parallel (bool): true when package supports parallel builds
-        command_line (int/None): command line override
-        config_default (int/None): config default number of jobs
-        max_cpus (int/None): maximum number of CPUs available. When None, this
-                             value is automatically determined.
+        parallel (bool or None): true when package supports parallel builds
+        command_line (int or None): command line override
+        config_default (int or None): config default number of jobs
+        max_cpus (int or None): maximum number of CPUs available. When None, this
+            value is automatically determined.
     """
     if not parallel:
         return 1
@@ -685,14 +685,14 @@ def get_std_cmake_args(pkg):
     """List of standard arguments used if a package is a CMakePackage.
 
     Returns:
-        list of str: standard arguments that would be used if this
+        list: standard arguments that would be used if this
         package were a CMakePackage instance.
 
     Args:
-        pkg (PackageBase): package under consideration
+        pkg (spack.package.PackageBase): package under consideration
 
     Returns:
-        list of str: arguments for cmake
+        list: arguments for cmake
     """
     return spack.build_systems.cmake.CMakePackage._std_args(pkg)
 
@@ -701,14 +701,14 @@ def get_std_meson_args(pkg):
     """List of standard arguments used if a package is a MesonPackage.
 
     Returns:
-        list of str: standard arguments that would be used if this
+        list: standard arguments that would be used if this
         package were a MesonPackage instance.
 
     Args:
-        pkg (PackageBase): package under consideration
+        pkg (spack.package.PackageBase): package under consideration
 
     Returns:
-        list of str: arguments for meson
+        list: arguments for meson
     """
     return spack.build_systems.meson.MesonPackage._std_args(pkg)
 
@@ -738,7 +738,7 @@ def load_external_modules(pkg):
     associated with them.
 
     Args:
-        pkg (PackageBase): package to load deps for
+        pkg (spack.package.PackageBase): package to load deps for
     """
     for dep in list(pkg.spec.traverse()):
         external_modules = dep.external_modules or []
@@ -864,7 +864,7 @@ def modifications_from_dependencies(spec, context, custom_mods_only=True):
     CMAKE_PREFIX_PATH, or PKG_CONFIG_PATH).
 
     Args:
-        spec (Spec): spec for which we want the modifications
+        spec (spack.spec.Spec): spec for which we want the modifications
         context (str): either 'build' for build-time modifications or 'run'
             for run-time modifications
     """
@@ -1062,9 +1062,9 @@ def start_build_process(pkg, function, kwargs):
 
     Args:
 
-        pkg (PackageBase): package whose environment we should set up the
+        pkg (spack.package.PackageBase): package whose environment we should set up the
             child process for.
-        function (callable): argless function to run in the child
+        function (typing.Callable): argless function to run in the child
             process.
 
     Usage::
@@ -1149,7 +1149,7 @@ def get_package_context(traceback, context=3):
     """Return some context for an error message when the build fails.
 
     Args:
-        traceback (traceback): A traceback from some exception raised during
+        traceback: A traceback from some exception raised during
             install
 
         context (int): Lines of context to show before and after the line
diff --git a/lib/spack/spack/build_systems/autotools.py b/lib/spack/spack/build_systems/autotools.py
index 7ded0245de..03923e3e51 100644
--- a/lib/spack/spack/build_systems/autotools.py
+++ b/lib/spack/spack/build_systems/autotools.py
@@ -30,7 +30,7 @@ class AutotoolsPackage(PackageBase):
 
     They all have sensible defaults and for many packages the only thing
     necessary will be to override the helper method
-    :py:meth:`~.AutotoolsPackage.configure_args`.
+    :meth:`~spack.build_systems.autotools.AutotoolsPackage.configure_args`.
     For a finer tuning you may also override:
 
         +-----------------------------------------------+--------------------+
@@ -331,7 +331,7 @@ class AutotoolsPackage(PackageBase):
 
     def configure(self, spec, prefix):
         """Runs configure with the arguments specified in
-        :py:meth:`~.AutotoolsPackage.configure_args`
+        :meth:`~spack.build_systems.autotools.AutotoolsPackage.configure_args`
         and an appropriately set prefix.
         """
         options = getattr(self, 'configure_flag_args', [])
@@ -376,8 +376,8 @@ class AutotoolsPackage(PackageBase):
             activation_value=None
     ):
         """This function contains the current implementation details of
-        :py:meth:`~.AutotoolsPackage.with_or_without` and
-        :py:meth:`~.AutotoolsPackage.enable_or_disable`.
+        :meth:`~spack.build_systems.autotools.AutotoolsPackage.with_or_without` and
+        :meth:`~spack.build_systems.autotools.AutotoolsPackage.enable_or_disable`.
 
         Args:
             name (str): name of the variant that is being processed
@@ -385,7 +385,7 @@ class AutotoolsPackage(PackageBase):
                 case of ``with_or_without``)
             deactivation_word (str): the default deactivation word ('without'
                 in the case of ``with_or_without``)
-            activation_value (callable): callable that accepts a single
+            activation_value (typing.Callable): callable that accepts a single
                 value. This value is either one of the allowed values for a
                 multi-valued variant or the name of a bool-valued variant.
                 Returns the parameter to be used when the value is activated.
@@ -420,7 +420,7 @@ class AutotoolsPackage(PackageBase):
             for ``<spec-name> foo=x +bar``
 
         Returns:
-            list of strings that corresponds to the activation/deactivation
+            list: list of strings that corresponds to the activation/deactivation
             of the variant that has been processed
 
         Raises:
@@ -501,7 +501,7 @@ class AutotoolsPackage(PackageBase):
 
         Args:
             name (str): name of a valid multi-valued variant
-            activation_value (callable): callable that accepts a single
+            activation_value (typing.Callable): callable that accepts a single
                 value and returns the parameter to be used leading to an entry
                 of the type ``--with-{name}={parameter}``.
 
@@ -514,12 +514,13 @@ class AutotoolsPackage(PackageBase):
         return self._activate_or_not(name, 'with', 'without', activation_value)
 
     def enable_or_disable(self, name, activation_value=None):
-        """Same as :py:meth:`~.AutotoolsPackage.with_or_without` but substitute
-        ``with`` with ``enable`` and ``without`` with ``disable``.
+        """Same as
+        :meth:`~spack.build_systems.autotools.AutotoolsPackage.with_or_without`
+        but substitute ``with`` with ``enable`` and ``without`` with ``disable``.
 
         Args:
             name (str): name of a valid multi-valued variant
-            activation_value (callable): if present accepts a single value
+            activation_value (typing.Callable): if present accepts a single value
                 and returns the parameter to be used leading to an entry of the
                 type ``--enable-{name}={parameter}``
 
diff --git a/lib/spack/spack/build_systems/cmake.py b/lib/spack/spack/build_systems/cmake.py
index acf4a9dc53..a3a1bb51e3 100644
--- a/lib/spack/spack/build_systems/cmake.py
+++ b/lib/spack/spack/build_systems/cmake.py
@@ -236,7 +236,7 @@ class CMakePackage(PackageBase):
         of ``cmake_var``.
 
         This utility function is similar to
-        :py:meth:`~.AutotoolsPackage.with_or_without`.
+        :meth:`~spack.build_systems.autotools.AutotoolsPackage.with_or_without`.
 
         Examples:
 
diff --git a/lib/spack/spack/build_systems/intel.py b/lib/spack/spack/build_systems/intel.py
index 2049669aea..427cb75e49 100644
--- a/lib/spack/spack/build_systems/intel.py
+++ b/lib/spack/spack/build_systems/intel.py
@@ -368,7 +368,7 @@ class IntelPackage(PackageBase):
                 toplevel psxevars.sh or equivalent file to source (and thus by
                 the modulefiles that Spack produces).
 
-            version_globs (list of str): Suffix glob patterns (most specific
+            version_globs (list): Suffix glob patterns (most specific
                 first) expected to qualify suite_dir_name to its fully
                 version-specific install directory (as opposed to a
                 compatibility directory or symlink).
diff --git a/lib/spack/spack/cmd/__init__.py b/lib/spack/spack/cmd/__init__.py
index fc6b860350..3944d5450e 100644
--- a/lib/spack/spack/cmd/__init__.py
+++ b/lib/spack/spack/cmd/__init__.py
@@ -216,10 +216,10 @@ def disambiguate_spec(spec, env, local=False, installed=True, first=False):
         spec (spack.spec.Spec): a spec to disambiguate
         env (spack.environment.Environment): a spack environment,
             if one is active, or None if no environment is active
-        local (boolean, default False): do not search chained spack instances
-        installed (boolean or any, or spack.database.InstallStatus or iterable
-            of spack.database.InstallStatus): install status argument passed to
-            database query. See ``spack.database.Database._query`` for details.
+        local (bool): do not search chained spack instances
+        installed (bool or spack.database.InstallStatus or typing.Iterable):
+            install status argument passed to database query.
+            See ``spack.database.Database._query`` for details.
     """
     hashes = env.all_hashes() if env else None
     return disambiguate_spec_from_hashes(spec, hashes, local, installed, first)
@@ -231,11 +231,11 @@ def disambiguate_spec_from_hashes(spec, hashes, local=False,
 
     Arguments:
         spec (spack.spec.Spec): a spec to disambiguate
-        hashes (iterable): a set of hashes of specs among which to disambiguate
-        local (boolean, default False): do not search chained spack instances
-        installed (boolean or any, or spack.database.InstallStatus or iterable
-            of spack.database.InstallStatus): install status argument passed to
-            database query. See ``spack.database.Database._query`` for details.
+        hashes (typing.Iterable): a set of hashes of specs among which to disambiguate
+        local (bool): do not search chained spack instances
+        installed (bool or spack.database.InstallStatus or typing.Iterable):
+            install status argument passed to database query.
+            See ``spack.database.Database._query`` for details.
     """
     if local:
         matching_specs = spack.store.db.query_local(spec, hashes=hashes,
@@ -333,9 +333,8 @@ def display_specs(specs, args=None, **kwargs):
     namespace.
 
     Args:
-        specs (list of spack.spec.Spec): the specs to display
-        args (optional argparse.Namespace): namespace containing
-            formatting arguments
+        specs (list): the specs to display
+        args (argparse.Namespace or None): namespace containing formatting arguments
 
     Keyword Args:
         paths (bool): Show paths with each displayed spec
@@ -348,9 +347,9 @@ def display_specs(specs, args=None, **kwargs):
         indent (int): indent each line this much
         groups (bool): display specs grouped by arch/compiler (default True)
         decorators (dict): dictionary mappng specs to decorators
-        header_callback (function): called at start of arch/compiler groups
+        header_callback (typing.Callable): called at start of arch/compiler groups
         all_headers (bool): show headers even when arch/compiler aren't defined
-        output (stream): A file object to write to. Default is ``sys.stdout``
+        output (typing.IO): A file object to write to. Default is ``sys.stdout``
 
     """
     def get_arg(name, default=None):
diff --git a/lib/spack/spack/cmd/analyze.py b/lib/spack/spack/cmd/analyze.py
index c2a6ec6a27..0bdf47e73f 100644
--- a/lib/spack/spack/cmd/analyze.py
+++ b/lib/spack/spack/cmd/analyze.py
@@ -58,9 +58,9 @@ def analyze_spec(spec, analyzers=None, outdir=None, monitor=None, overwrite=Fals
     analyze_spec(spec, args.analyzers, args.outdir, monitor)
 
     Args:
-        spec (Spec): spec object of installed package
+        spec (spack.spec.Spec): spec object of installed package
         analyzers (list): list of analyzer (keys) to run
-        monitor (monitor.SpackMonitorClient): a monitor client
+        monitor (spack.monitor.SpackMonitorClient): a monitor client
         overwrite (bool): overwrite result if already exists
     """
     analyzers = analyzers or list(spack.analyzers.analyzer_types.keys())
diff --git a/lib/spack/spack/cmd/buildcache.py b/lib/spack/spack/cmd/buildcache.py
index ebad6bb4b7..ea1297c726 100644
--- a/lib/spack/spack/cmd/buildcache.py
+++ b/lib/spack/spack/cmd/buildcache.py
@@ -239,12 +239,13 @@ def find_matching_specs(pkgs, allow_multiple_matches=False, env=None):
        concretized specs given from cli
 
     Args:
-        pkgs (string): spec to be matched against installed packages
+        pkgs (str): spec to be matched against installed packages
         allow_multiple_matches (bool): if True multiple matches are admitted
-        env (Environment): active environment, or ``None`` if there is not one
+        env (spack.environment.Environment or None): active environment, or ``None``
+            if there is not one
 
     Return:
-        list of specs
+        list: list of specs
     """
     hashes = env.all_hashes() if env else None
 
diff --git a/lib/spack/spack/cmd/create.py b/lib/spack/spack/cmd/create.py
index a680848673..bccf3bf66d 100644
--- a/lib/spack/spack/cmd/create.py
+++ b/lib/spack/spack/cmd/create.py
@@ -636,7 +636,7 @@ def get_name(args):
     provided, extract the name from that. Otherwise, use a default.
 
     Args:
-        args (param argparse.Namespace): The arguments given to
+        args (argparse.Namespace): The arguments given to
             ``spack create``
 
     Returns:
@@ -709,8 +709,7 @@ def get_versions(args, name):
         name (str): The name of the package
 
     Returns:
-        str and BuildSystemGuesser: Versions and hashes, and a
-            BuildSystemGuesser object
+        tuple: versions and hashes, and a BuildSystemGuesser object
     """
 
     # Default version with hash
@@ -794,7 +793,8 @@ def get_repository(args, name):
         name (str): The name of the package to create
 
     Returns:
-        Repo: A Repo object capable of determining the path to the package file
+        spack.repo.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/dependents.py b/lib/spack/spack/cmd/dependents.py
index 242a07da36..6097f46ff9 100644
--- a/lib/spack/spack/cmd/dependents.py
+++ b/lib/spack/spack/cmd/dependents.py
@@ -59,7 +59,7 @@ def get_dependents(pkg_name, ideps, transitive=False, dependents=None):
     Args:
         pkg_name (str): name of the package whose dependents should be returned
         ideps (dict): dictionary of dependents, from inverted_dependencies()
-        transitive (bool, optional): return transitive dependents when True
+        transitive (bool or None): return transitive dependents when True
     """
     if dependents is None:
         dependents = set()
diff --git a/lib/spack/spack/cmd/install.py b/lib/spack/spack/cmd/install.py
index 5a452a9232..f71a788ec1 100644
--- a/lib/spack/spack/cmd/install.py
+++ b/lib/spack/spack/cmd/install.py
@@ -198,9 +198,9 @@ def install_specs(cli_args, kwargs, specs):
     """Do the actual installation.
 
     Args:
-        cli_args (Namespace): argparse namespace with command arguments
+        cli_args (argparse.Namespace): argparse namespace with command arguments
         kwargs (dict):  keyword arguments
-        specs (list of tuples):  list of (abstract, concrete) spec tuples
+        specs (list):  list of (abstract, concrete) spec tuples
     """
 
     # handle active environment, if any
diff --git a/lib/spack/spack/cmd/uninstall.py b/lib/spack/spack/cmd/uninstall.py
index 9d787a70a2..ead4f8ac84 100644
--- a/lib/spack/spack/cmd/uninstall.py
+++ b/lib/spack/spack/cmd/uninstall.py
@@ -69,12 +69,13 @@ def find_matching_specs(env, specs, allow_multiple_matches=False, force=False):
        concretized specs given from cli
 
     Args:
-        env (Environment): active environment, or ``None`` if there is not one
+        env (spack.environment.Environment): active environment, or ``None``
+            if there is not one
         specs (list): list of specs to be matched against installed packages
         allow_multiple_matches (bool): if True multiple matches are admitted
 
     Return:
-        list of specs
+        list: list of specs
     """
     # constrain uninstall resolution to current environment if one is active
     hashes = env.all_hashes() if env else None
@@ -118,15 +119,13 @@ def installed_dependents(specs, env):
 
     Args:
         specs (list): list of Specs
-        env (Environment): the active environment, or None
+        env (spack.environment.Environment or None): the active environment, or None
 
     Returns:
-        (tuple of dicts): two mappings: one from specs to their dependent
-            environments in the active environment (or global scope if
-            there is no environment), and one from specs to their
-            dependents in *inactive* environments (empty if there is no
-            environment
-
+        tuple: two mappings: one from specs to their dependent environments in the
+        active environment (or global scope if there is no environment), and one from
+        specs to their dependents in *inactive* environments (empty if there is no
+        environment
     """
     active_dpts = {}
     inactive_dpts = {}
@@ -155,9 +154,9 @@ def dependent_environments(specs):
 
     Args:
         specs (list): list of Specs
-    Returns:
-        (dict): mapping from spec to lists of dependent Environments
 
+    Returns:
+        dict: mapping from spec to lists of dependent Environments
     """
     dependents = {}
     for env in ev.all_environments():
@@ -176,9 +175,10 @@ def inactive_dependent_environments(spec_envs):
     have no dependent environments.  Return the result.
 
     Args:
-        (dict): mapping from spec to lists of dependent Environments
+        spec_envs (dict): mapping from spec to lists of dependent Environments
+
     Returns:
-        (dict): mapping from spec to lists of *inactive* dependent Environments
+        dict: mapping from spec to lists of *inactive* dependent Environments
     """
     spec_inactive_envs = {}
     for spec, de_list in spec_envs.items():
@@ -203,7 +203,8 @@ def do_uninstall(env, specs, force):
     """Uninstalls all the specs in a list.
 
     Args:
-        env (Environment): active environment, or ``None`` if there is not one
+        env (spack.environment.Environment or None): active environment, or ``None``
+            if there is not one
         specs (list): list of specs to be uninstalled
         force (bool): force uninstallation (boolean)
     """
diff --git a/lib/spack/spack/cmd/url.py b/lib/spack/spack/cmd/url.py
index 1576a4f762..8d9232203f 100644
--- a/lib/spack/spack/cmd/url.py
+++ b/lib/spack/spack/cmd/url.py
@@ -502,7 +502,7 @@ def remove_separators(version):
     Unfortunately, this also means that 1.23 and 12.3 are equal.
 
     Args:
-        version (str or Version): A version
+        version (str or spack.version.Version): A version
 
     Returns:
         str: The version with all separator characters removed
diff --git a/lib/spack/spack/compilers/__init__.py b/lib/spack/spack/compilers/__init__.py
index 537e8211c3..d60ab971bc 100644
--- a/lib/spack/spack/compilers/__init__.py
+++ b/lib/spack/spack/compilers/__init__.py
@@ -135,8 +135,8 @@ def add_compilers_to_config(compilers, scope=None, init_config=True):
     """Add compilers to the config for the specified architecture.
 
     Arguments:
-      - compilers: a list of Compiler objects.
-      - scope:     configuration scope to modify.
+        compilers: a list of Compiler objects.
+        scope: configuration scope to modify.
     """
     compiler_config = get_compiler_config(scope, init_config)
     for compiler in compilers:
@@ -151,8 +151,8 @@ def remove_compiler_from_config(compiler_spec, scope=None):
     """Remove compilers from the config, by spec.
 
     Arguments:
-      - compiler_specs: a list of CompilerSpec objects.
-      - scope:          configuration scope to modify.
+        compiler_specs: a list of CompilerSpec objects.
+        scope: configuration scope to modify.
     """
     # Need a better way for this
     global _cache_config_file
@@ -544,8 +544,8 @@ def arguments_to_detect_version_fn(operating_system, paths):
     function by providing a method called with the same name.
 
     Args:
-        operating_system (OperatingSystem): the operating system on which
-            we are looking for compilers
+        operating_system (spack.architecture.OperatingSystem): the operating system
+            on which we are looking for compilers
         paths: paths to search for compilers
 
     Returns:
@@ -649,7 +649,7 @@ def make_compiler_list(detected_versions):
             valid version
 
     Returns:
-        list of Compiler objects
+        list: list of Compiler objects
     """
     group_fn = lambda x: (x.id, x.variation, x.language)
     sorted_compilers = sorted(detected_versions, key=group_fn)
@@ -715,7 +715,7 @@ def is_mixed_toolchain(compiler):
     False otherwise.
 
     Args:
-        compiler (Compiler): a valid compiler object
+        compiler (spack.compiler.Compiler): a valid compiler object
     """
     cc = os.path.basename(compiler.cc or '')
     cxx = os.path.basename(compiler.cxx or '')
diff --git a/lib/spack/spack/config.py b/lib/spack/spack/config.py
index 5ceaef8e7b..93399efb03 100644
--- a/lib/spack/spack/config.py
+++ b/lib/spack/spack/config.py
@@ -17,8 +17,8 @@ configuration system behaves.  The scopes are:
 And corresponding :ref:`per-platform scopes <platform-scopes>`. Important
 functions in this module are:
 
-* :py:func:`get_config`
-* :py:func:`update_config`
+* :func:`~spack.config.Configuration.get_config`
+* :func:`~spack.config.Configuration.update_config`
 
 ``get_config`` reads in YAML data for a particular scope and returns
 it. Callers can then modify the data and write it back with
@@ -722,7 +722,7 @@ def override(path_or_scope, value=None):
 
     Arguments:
         path_or_scope (ConfigScope or str): scope or single option to override
-        value (object, optional): value for the single option
+        value (object or None): value for the single option
 
     Temporarily push a scope on the current configuration, then remove it
     after the context completes. If a single option is provided, create
@@ -1163,7 +1163,7 @@ def default_modify_scope(section='config'):
     priority scope.
 
     Arguments:
-        section (boolean): Section for which to get the default scope.
+        section (bool): Section for which to get the default scope.
             If this is not 'compilers', a general (non-platform) scope is used.
     """
     if section == 'compilers':
diff --git a/lib/spack/spack/database.py b/lib/spack/spack/database.py
index 60e93ed49b..251d3964bc 100644
--- a/lib/spack/spack/database.py
+++ b/lib/spack/spack/database.py
@@ -171,13 +171,13 @@ class InstallRecord(object):
     dependents left.
 
     Args:
-        spec (Spec): spec tracked by the install record
+        spec (spack.spec.Spec): spec tracked by the install record
         path (str): path where the spec has been installed
         installed (bool): whether or not the spec is currently installed
         ref_count (int): number of specs that depend on this one
-        explicit (bool, optional): whether or not this spec was explicitly
+        explicit (bool or None): whether or not this spec was explicitly
             installed, or pulled-in as a dependency of something else
-        installation_time (time, optional): time of the installation
+        installation_time (datetime.datetime or None): time of the installation
     """
 
     def __init__(
@@ -256,36 +256,36 @@ _query_docstring = """
                 database.  If it is a spec, we'll evaluate
                 ``spec.satisfies(query_spec)``
 
-            known (bool or any, optional): Specs that are "known" are those
+            known (bool or None): Specs that are "known" are those
                 for which Spack can locate a ``package.py`` file -- i.e.,
                 Spack "knows" how to install them.  Specs that are unknown may
                 represent packages that existed in a previous version of
                 Spack, but have since either changed their name or
                 been removed
 
-            installed (bool or any, or InstallStatus or iterable of
-                InstallStatus, optional): if ``True``, includes only installed
+            installed (bool or InstallStatus or typing.Iterable or None):
+                if ``True``, includes only installed
                 specs in the search; if ``False`` only missing specs, and if
                 ``any``, all specs in database. If an InstallStatus or iterable
                 of InstallStatus, returns specs whose install status
                 (installed, deprecated, or missing) matches (one of) the
                 InstallStatus. (default: True)
 
-            explicit (bool or any, optional): A spec that was installed
+            explicit (bool or None): A spec that was installed
                 following a specific user request is marked as explicit. If
                 instead it was pulled-in as a dependency of a user requested
                 spec it's considered implicit.
 
-            start_date (datetime, optional): filters the query discarding
-                specs that have been installed before ``start_date``.
+            start_date (datetime.datetime or None): filters the query
+                discarding specs that have been installed before ``start_date``.
 
-            end_date (datetime, optional): filters the query discarding
+            end_date (datetime.datetime or None): filters the query discarding
                 specs that have been installed after ``end_date``.
 
-            hashes (container): list or set of hashes that we can use to
+            hashes (typing.Container): list or set of hashes that we can use to
                 restrict the search
 
-            in_buildcache (bool or any, optional): Specs that are marked in
+            in_buildcache (bool or None): Specs that are marked in
                 this database as part of an associated binary cache are
                 ``in_buildcache``. All other specs are not. This field is used
                 for querying mirror indices. Default is ``any``.
@@ -449,7 +449,7 @@ class Database(object):
         see `mark_failed()`.
 
         Args:
-            spec (Spec): the spec whose failure indicators are being removed
+            spec (spack.spec.Spec): the spec whose failure indicators are being removed
             force (bool): True if the failure information should be cleared
                 when a prefix failure lock exists for the file or False if
                 the failure should not be cleared (e.g., it may be
@@ -1391,10 +1391,10 @@ class Database(object):
 
         Arguments:
             dag_hash (str): hash (or hash prefix) to look up
-            default (object, optional): default value to return if dag_hash is
+            default (object or None): default value to return if dag_hash is
                 not in the DB (default: None)
-            installed (bool or any, or InstallStatus or iterable of
-                InstallStatus, optional): if ``True``, includes only installed
+            installed (bool or InstallStatus or typing.Iterable or None):
+                if ``True``, includes only installed
                 specs in the search; if ``False`` only missing specs, and if
                 ``any``, all specs in database. If an InstallStatus or iterable
                 of InstallStatus, returns specs whose install status
@@ -1417,14 +1417,13 @@ class Database(object):
 
         Arguments:
             dag_hash (str): hash (or hash prefix) to look up
-            default (object, optional): default value to return if dag_hash is
+            default (object or None): default value to return if dag_hash is
                 not in the DB (default: None)
-            installed (bool or any, or InstallStatus or iterable of
-                InstallStatus, optional): if ``True``, includes only installed
-                specs in the search; if ``False`` only missing specs, and if
-                ``any``, all specs in database. If an InstallStatus or iterable
-                of InstallStatus, returns specs whose install status
-                (installed, deprecated, or missing) matches (one of) the
+            installed (bool or InstallStatus or typing.Iterable or None):
+                if ``True``, includes only installed specs in the search; if ``False``
+                only missing specs, and if ``any``, all specs in database. If an
+                InstallStatus or iterable of InstallStatus, returns specs whose install
+                status (installed, deprecated, or missing) matches (one of) the
                 InstallStatus. (default: any)
 
         ``installed`` defaults to ``any`` so that we can refer to any
@@ -1596,7 +1595,7 @@ class Database(object):
         Update the spec's explicit state in the database.
 
         Args:
-            spec (Spec): the spec whose install record is being updated
+            spec (spack.spec.Spec): the spec whose install record is being updated
             explicit (bool): ``True`` if the package was requested explicitly
                 by the user, ``False`` if it was pulled in as a dependency of
                 an explicit package.
diff --git a/lib/spack/spack/directives.py b/lib/spack/spack/directives.py
index d9195d9ecd..91deedbb5a 100644
--- a/lib/spack/spack/directives.py
+++ b/lib/spack/spack/directives.py
@@ -54,7 +54,7 @@ else:
     from collections import Sequence
 
 
-__all__ = []
+__all__ = ['DirectiveError', 'DirectiveMeta']
 
 #: These are variant names used by Spack internally; packages can't use them
 reserved_names = ['patches', 'dev_path']
@@ -85,7 +85,7 @@ def make_when_spec(value):
     as part of concretization.
 
     Arguments:
-        value (Spec or bool): a conditional Spec or a constant ``bool``
+        value (spack.spec.Spec or bool): a conditional Spec or a constant ``bool``
            value indicating when a directive should be applied.
 
     """
@@ -187,12 +187,16 @@ class DirectiveMeta(type):
 
         Here's an example directive:
 
+        .. code-block:: python
+
             @directive(dicts='versions')
             version(pkg, ...):
                 ...
 
         This directive allows you write:
 
+        .. code-block:: python
+
             class Foo(Package):
                 version(...)
 
@@ -392,8 +396,8 @@ def conflicts(conflict_spec, when=None, msg=None):
         conflicts('%intel', when='+foo')
 
     Args:
-        conflict_spec (Spec): constraint defining the known conflict
-        when (Spec): optional constraint that triggers the conflict
+        conflict_spec (spack.spec.Spec): constraint defining the known conflict
+        when (spack.spec.Spec): optional constraint that triggers the conflict
         msg (str): optional user defined message
     """
     def _execute_conflicts(pkg):
@@ -413,11 +417,11 @@ def depends_on(spec, when=None, type=default_deptype, patches=None):
     """Creates a dict of deps with specs defining when they apply.
 
     Args:
-        spec (Spec or str): the package and constraints depended on
-        when (Spec or str): when the dependent satisfies this, it has
+        spec (spack.spec.Spec or str): the package and constraints depended on
+        when (spack.spec.Spec or str): when the dependent satisfies this, it has
             the dependency represented by ``spec``
-        type (str or tuple of str): str or tuple of legal Spack deptypes
-        patches (obj or list): single result of ``patch()`` directive, a
+        type (str or tuple): str or tuple of legal Spack deptypes
+        patches (typing.Callable or list): single result of ``patch()`` directive, a
             ``str`` to be passed to ``patch``, or a list of these
 
     This directive is to be used inside a Package definition to declare
@@ -495,7 +499,7 @@ def patch(url_or_filename, level=1, when=None, working_dir=".", **kwargs):
     Args:
         url_or_filename (str): url or relative filename of the patch
         level (int): patch level (as in the patch shell command)
-        when (Spec): optional anonymous spec that specifies when to apply
+        when (spack.spec.Spec): optional anonymous spec that specifies when to apply
             the patch
         working_dir (str): dir to change to before applying
 
@@ -559,12 +563,12 @@ def variant(
             specified otherwise the default will be False for a boolean
             variant and 'nothing' for a multi-valued variant
         description (str): description of the purpose of the variant
-        values (tuple or callable): either a tuple of strings containing the
+        values (tuple or typing.Callable): either a tuple of strings containing the
             allowed values, or a callable accepting one value and returning
             True if it is valid
         multi (bool): if False only one value per spec is allowed for
             this variant
-        validator (callable): optional group validator to enforce additional
+        validator (typing.Callable): optional group validator to enforce additional
             logic. It receives the package name, the variant name and a tuple
             of values and should raise an instance of SpackError if the group
             doesn't meet the additional constraints
diff --git a/lib/spack/spack/environment.py b/lib/spack/spack/environment.py
index c41d567bce..f2ed7f39b0 100644
--- a/lib/spack/spack/environment.py
+++ b/lib/spack/spack/environment.py
@@ -116,11 +116,12 @@ def activate(
         use_env_repo (bool): use the packages exactly as they appear in the
             environment's repository
         add_view (bool): generate commands to add view to path variables
-        shell (string): One of `sh`, `csh`, `fish`.
-        prompt (string): string to add to the users prompt, or None
+        shell (str): One of `sh`, `csh`, `fish`.
+        prompt (str): string to add to the users prompt, or None
 
     Returns:
-        cmds: Shell commands to activate environment.
+        str: Shell commands to activate environment.
+
     TODO: environment to use the activated spack environment.
     """
     global _active_environment
@@ -198,10 +199,10 @@ def deactivate(shell='sh'):
     """Undo any configuration or repo settings modified by ``activate()``.
 
     Arguments:
-        shell (string): One of `sh`, `csh`, `fish`. Shell style to use.
+        shell (str): One of `sh`, `csh`, `fish`. Shell style to use.
 
     Returns:
-        (string): shell commands for `shell` to undo environment variables
+        str: shell commands for `shell` to undo environment variables
 
     """
     global _active_environment
@@ -272,7 +273,7 @@ def find_environment(args):
     If an environment is found, read it in.  If not, return None.
 
     Arguments:
-        args (Namespace): argparse namespace wtih command arguments
+        args (argparse.Namespace): argparse namespace wtih command arguments
 
     Returns:
         (Environment): a found environment, or ``None``
@@ -322,7 +323,7 @@ def get_env(args, cmd_name, required=False):
     message that says the calling command *needs* an active environment.
 
     Arguments:
-        args (Namespace): argparse namespace wtih command arguments
+        args (argparse.Namespace): argparse namespace wtih command arguments
         cmd_name (str): name of calling command
         required (bool): if ``True``, raise an exception when no environment
             is found; if ``False``, just return ``None``
@@ -550,7 +551,7 @@ class ViewDescriptor(object):
         Raise if new is None and there is no current view
 
         Arguments:
-            new (string or None): If a string, create a FilesystemView
+            new (str or None): If a string, create a FilesystemView
                 rooted at that path. Default None. This should only be used to
                 regenerate the view, and cannot be used to access specs.
         """
@@ -851,7 +852,7 @@ class Environment(object):
         """Clear the contents of the environment
 
         Arguments:
-            re_read (boolean): If True, do not clear ``new_specs`` nor
+            re_read (bool): If True, do not clear ``new_specs`` nor
                 ``new_installs`` values. These values cannot be read from
                 yaml, and need to be maintained when re-reading an existing
                 environment.
@@ -1119,11 +1120,11 @@ class Environment(object):
         """Add dev-build info for package
 
         Args:
-            spec (Spec): Set constraints on development specs. Must include a
+            spec (spack.spec.Spec): Set constraints on development specs. Must include a
                 concrete version.
-            path (string): Path to find code for developer builds. Relative
+            path (str): Path to find code for developer builds. Relative
                 paths will be resolved relative to the environment.
-            clone (bool, default False): Clone the package code to the path.
+            clone (bool): Clone the package code to the path.
                 If clone is False Spack will assume the code is already present
                 at ``path``.
 
@@ -1552,7 +1553,7 @@ class Environment(object):
         that needs to be done separately with a call to write().
 
         Args:
-            args (Namespace): argparse namespace with command arguments
+            args (argparse.Namespace): argparse namespace with command arguments
             install_args (dict): keyword install arguments
         """
         self.install_specs(None, args=args, **install_args)
diff --git a/lib/spack/spack/fetch_strategy.py b/lib/spack/spack/fetch_strategy.py
index 3eee59349e..f5eecdcb5d 100644
--- a/lib/spack/spack/fetch_strategy.py
+++ b/lib/spack/spack/fetch_strategy.py
@@ -1254,8 +1254,9 @@ class HgFetchStrategy(VCSFetchStrategy):
 
     @property
     def hg(self):
-        """:returns: The hg executable
-        :rtype: Executable
+        """
+        Returns:
+            Executable: the hg executable
         """
         if not self._hg:
             self._hg = which('hg', required=True)
@@ -1405,7 +1406,7 @@ def from_kwargs(**kwargs):
             ``version()`` directive in a package.
 
     Returns:
-        fetch_strategy: The fetch strategy that matches the args, based
+        typing.Callable: The fetch strategy that matches the args, based
             on attribute names (e.g., ``git``, ``hg``, etc.)
 
     Raises:
diff --git a/lib/spack/spack/install_test.py b/lib/spack/spack/install_test.py
index 9142bb448c..200eaed4ec 100644
--- a/lib/spack/spack/install_test.py
+++ b/lib/spack/spack/install_test.py
@@ -28,7 +28,7 @@ def get_escaped_text_output(filename):
         filename (str): path to the file
 
     Returns:
-        (list of str): escaped text lines read from the file
+        list: escaped text lines read from the file
     """
     with open(filename, 'r') as f:
         # Ensure special characters are escaped as needed
diff --git a/lib/spack/spack/installer.py b/lib/spack/spack/installer.py
index 0cbb71ef4b..1d0b221257 100644
--- a/lib/spack/spack/installer.py
+++ b/lib/spack/spack/installer.py
@@ -93,7 +93,7 @@ def _check_last_phase(pkg):
     package already.
 
     Args:
-        pkg (PackageBase): the package being installed
+        pkg (spack.package.PackageBase): the package being installed
 
     Raises:
         ``BadInstallPhase`` if stop_before or last phase is invalid
@@ -115,10 +115,11 @@ def _handle_external_and_upstream(pkg, explicit):
     database if it is external package.
 
     Args:
-        pkg (Package): the package whose installation is under consideration
+        pkg (spack.package.Package): the package whose installation is under
+            consideration
         explicit (bool): the package was explicitly requested by the user
     Return:
-        (bool): ``True`` if the package is external or upstream (so not to
+        bool: ``True`` if the package is external or upstream (so not to
             be installed locally), otherwise, ``True``
     """
     # For external packages the workflow is simplified, and basically
@@ -148,7 +149,7 @@ def _do_fake_install(pkg):
     and libraries.
 
     Args:
-        pkg (PackageBase): the package whose installation is to be faked
+        pkg (spack.package.PackageBase): the package whose installation is to be faked
     """
 
     command = pkg.name
@@ -194,15 +195,14 @@ def _packages_needed_to_bootstrap_compiler(compiler, architecture, pkgs):
         compiler (CompilerSpec): the compiler to bootstrap
         architecture (ArchSpec): the architecture for which to boostrap the
             compiler
-        pkgs (list of PackageBase): the packages that may need their compiler
+        pkgs (list): the packages that may need their compiler
             installed
 
     Return:
-        (list) list of tuples, (PackageBase, bool), for concretized compiler-
-            -related packages that need to be installed and bool values
-            specify whether the package is the bootstrap compiler
-            (``True``) or one of its dependencies (``False``).  The list
-            will be empty if there are no compilers.
+        list: list of tuples, (PackageBase, bool), for concretized compiler-related
+            packages that need to be installed and bool values specify whether the
+            package is the bootstrap compiler (``True``) or one of its dependencies
+            (``False``).  The list will be empty if there are no compilers.
     """
     tty.debug('Bootstrapping {0} compiler'.format(compiler))
     compilers = spack.compilers.compilers_for_spec(
@@ -260,7 +260,7 @@ def _install_from_cache(pkg, cache_only, explicit, unsigned=False,
     Extract the package from binary cache
 
     Args:
-        pkg (PackageBase): the package to install from the binary cache
+        pkg (spack.package.PackageBase): the package to install from the binary cache
         cache_only (bool): only extract from binary cache
         explicit (bool): ``True`` if installing the package was explicitly
             requested by the user, otherwise, ``False``
@@ -268,7 +268,7 @@ def _install_from_cache(pkg, cache_only, explicit, unsigned=False,
             otherwise, ``False``
 
     Return:
-        (bool) ``True`` if the package was extract from binary cache,
+        bool: ``True`` if the package was extract from binary cache,
             ``False`` otherwise
     """
     installed_from_cache = _try_install_from_binary_cache(
@@ -350,8 +350,8 @@ def _process_binary_cache_tarball(pkg, binary_spec, explicit, unsigned,
     Process the binary cache tarball.
 
     Args:
-        pkg (PackageBase): the package being installed
-        binary_spec (Spec): the spec  whose cache has been confirmed
+        pkg (spack.package.PackageBase): the package being installed
+        binary_spec (spack.spec.Spec): the spec  whose cache has been confirmed
         explicit (bool): the package was explicitly requested by the user
         unsigned (bool): ``True`` if binary package signatures to be checked,
             otherwise, ``False``
@@ -359,7 +359,7 @@ def _process_binary_cache_tarball(pkg, binary_spec, explicit, unsigned,
             attempting to download the tarball
 
     Return:
-        (bool) ``True`` if the package was extracted from binary cache,
+        bool: ``True`` if the package was extracted from binary cache,
             else ``False``
     """
     tarball = binary_distribution.download_tarball(
@@ -385,7 +385,7 @@ def _try_install_from_binary_cache(pkg, explicit, unsigned=False,
     Try to extract the package from binary cache.
 
     Args:
-        pkg (PackageBase): the package to be extracted from binary cache
+        pkg (spack.package.PackageBase): the package to be extracted from binary cache
         explicit (bool): the package was explicitly requested by the user
         unsigned (bool): ``True`` if binary package signatures to be checked,
             otherwise, ``False``
@@ -423,7 +423,7 @@ def combine_phase_logs(phase_log_files, log_path):
 
     Args:
         phase_log_files (list): a list or iterator of logs to combine
-        log_path (path): the path to combine them to
+        log_path (str): the path to combine them to
     """
 
     with open(log_path, 'w') as log_file:
@@ -441,7 +441,7 @@ def dump_packages(spec, path):
     node in the DAG.
 
     Args:
-        spec (Spec): the Spack spec whose package information is to be dumped
+        spec (spack.spec.Spec): the Spack spec whose package information is to be dumped
         path (str): the path to the build packages directory
     """
     fs.mkdirp(path)
@@ -498,10 +498,10 @@ def get_dependent_ids(spec):
     Return a list of package ids for the spec's dependents
 
     Args:
-        spec (Spec): Concretized spec
+        spec (spack.spec.Spec): Concretized spec
 
     Returns:
-        (list of str): list of package ids
+        list: list of package ids
     """
     return [package_id(d.package) for d in spec.dependents()]
 
@@ -512,10 +512,10 @@ def install_msg(name, pid):
 
     Args:
         name (str): Name/id of the package being installed
-        pid (id): id of the installer process
+        pid (int): id of the installer process
 
     Return:
-        (str) Colorized installing message
+        str: Colorized installing message
     """
     pre = '{0}: '.format(pid) if tty.show_pid() else ''
     return pre + colorize('@*{Installing} @*g{%s}' % name)
@@ -526,7 +526,7 @@ def log(pkg):
     Copy provenance into the install directory on success
 
     Args:
-        pkg (Package): the package that was built and installed
+        pkg (spack.package.Package): the package that was built and installed
     """
     packages_dir = spack.store.layout.build_packages_path(pkg.spec)
 
@@ -608,7 +608,8 @@ def package_id(pkg):
     and packages for combinatorial environments.
 
     Args:
-        pkg (PackageBase): the package from which the identifier is derived
+        pkg (spack.package.PackageBase): the package from which the identifier is
+            derived
     """
     if not pkg.spec.concrete:
         raise ValueError("Cannot provide a unique, readable id when "
@@ -631,11 +632,11 @@ class PackageInstaller(object):
         """ Initialize the installer.
 
         Args:
-            installs (list of (pkg, install_args)): list of tuples, where each
+            installs (list): list of tuples, where each
                 tuple consists of a package (PackageBase) and its associated
                  install arguments (dict)
         Return:
-            (PackageInstaller) instance
+            PackageInstaller: instance
         """
         # List of build requests
         self.build_requests = [BuildRequest(pkg, install_args)
@@ -691,7 +692,8 @@ class PackageInstaller(object):
         Args:
             compiler: the compiler to boostrap
             architecture: the architecture for which to bootstrap the compiler
-            pkgs (PackageBase): the package with possible compiler dependencies
+            pkgs (spack.package.PackageBase): the package with possible compiler
+                dependencies
             request (BuildRequest): the associated install request
             all_deps (defaultdict(set)): dictionary of all dependencies and
                 associated dependents
@@ -707,7 +709,7 @@ class PackageInstaller(object):
         Creates and queus the initial build task for the package.
 
         Args:
-            pkg (Package): the package to be built and installed
+            pkg (spack.package.Package): the package to be built and installed
             request (BuildRequest or None): the associated install request
                  where ``None`` can be used to indicate the package was
                  explicitly requested by the user
@@ -726,7 +728,7 @@ class PackageInstaller(object):
         """Determine if the spec is flagged as installed in the database
 
         Args:
-            spec (Spec): spec whose database install status is being checked
+            spec (spack.spec.Spec): spec whose database install status is being checked
 
         Return:
             (rec, installed_in_db) tuple where rec is the database record, or
@@ -887,7 +889,7 @@ class PackageInstaller(object):
         Cleanup the build task for the spec
 
         Args:
-            pkg (PackageBase): the package being installed
+            pkg (spack.package.PackageBase): the package being installed
         """
         self._remove_task(package_id(pkg))
 
@@ -901,7 +903,7 @@ class PackageInstaller(object):
         already locked.
 
         Args:
-            pkg (PackageBase): the package being locally installed
+            pkg (spack.package.PackageBase): the package being locally installed
         """
         pkg_id = package_id(pkg)
         pre = "{0} cannot be installed locally:".format(pkg_id)
@@ -933,7 +935,7 @@ class PackageInstaller(object):
 
         Args:
             lock_type (str): 'read' for a read lock, 'write' for a write lock
-            pkg (PackageBase): the package whose spec is being installed
+            pkg (spack.package.PackageBase): the package whose spec is being installed
 
         Return:
             (lock_type, lock) tuple where lock will be None if it could not
@@ -1294,7 +1296,7 @@ class PackageInstaller(object):
         Write a small metadata file with the current spack environment.
 
         Args:
-            pkg (Package): the package to be built and installed
+            pkg (spack.package.Package): the package to be built and installed
         """
         if not os.path.exists(pkg.spec.prefix):
             tty.verbose('Creating the installation directory {0}'
@@ -1369,9 +1371,9 @@ class PackageInstaller(object):
         known dependents.
 
         Args:
-            pkg (Package): Package that has been installed locally, externally
-                or upstream
-            dependent_ids (list of str or None): list of the package's
+            pkg (spack.package.Package): Package that has been installed locally,
+                externally or upstream
+            dependent_ids (list or None): list of the package's
                 dependent ids, or None if the dependent ids are limited to
                 those maintained in the package (dependency DAG)
         """
@@ -1422,7 +1424,7 @@ class PackageInstaller(object):
         Install the requested package(s) and or associated dependencies.
 
         Args:
-            pkg (Package): the package to be built and installed"""
+            pkg (spack.package.Package): the package to be built and installed"""
 
         self._init_queue()
         fail_fast_err = 'Terminating after first install failure'
@@ -1833,7 +1835,7 @@ class BuildTask(object):
         Instantiate a build task for a package.
 
         Args:
-            pkg (Package): the package to be built and installed
+            pkg (spack.package.Package): the package to be built and installed
             request (BuildRequest or None): the associated install request
                  where ``None`` can be used to indicate the package was
                  explicitly requested by the user
@@ -1841,7 +1843,7 @@ class BuildTask(object):
             start (int): the initial start time for the package, in seconds
             attempts (int): the number of attempts to install the package
             status (str): the installation status
-            installed (list of str): the identifiers of packages that have
+            installed (list): the identifiers of packages that have
                 been installed so far
         """
 
@@ -1983,7 +1985,7 @@ class BuildTask(object):
         Ensure the dependency is not considered to still be uninstalled.
 
         Args:
-            installed (list of str): the identifiers of packages that have
+            installed (list): the identifiers of packages that have
                 been installed so far
         """
         now_installed = self.uninstalled_deps & set(installed)
@@ -2024,7 +2026,7 @@ class BuildRequest(object):
         Instantiate a build request for a package.
 
         Args:
-            pkg (Package): the package to be built and installed
+            pkg (spack.package.Package): the package to be built and installed
             install_args (dict): the install arguments associated with ``pkg``
         """
         # Ensure dealing with a package that has a concrete spec
@@ -2099,10 +2101,11 @@ class BuildRequest(object):
         """Determine the required dependency types for the associated package.
 
         Args:
-            pkg (PackageBase): explicit or implicit package being installed
+            pkg (spack.package.PackageBase): explicit or implicit package being
+                installed
 
         Returns:
-            (tuple) required dependency type(s) for the package
+            tuple: required dependency type(s) for the package
         """
         deptypes = ['link', 'run']
         include_build_deps = self.install_args.get('include_build_deps')
@@ -2121,10 +2124,11 @@ class BuildRequest(object):
         """Determine if the tests should be run for the provided packages
 
         Args:
-            pkg (PackageBase): explicit or implicit package being installed
+            pkg (spack.package.PackageBase): explicit or implicit package being
+                installed
 
         Returns:
-            (bool) ``True`` if they should be run; ``False`` otherwise
+            bool: ``True`` if they should be run; ``False`` otherwise
         """
         tests = self.install_args.get('tests', False)
         return tests is True or (tests and pkg.name in tests)
diff --git a/lib/spack/spack/main.py b/lib/spack/spack/main.py
index fcf6369df7..d237db8904 100644
--- a/lib/spack/spack/main.py
+++ b/lib/spack/spack/main.py
@@ -530,7 +530,7 @@ class SpackCommand(object):
         """Invoke this SpackCommand.
 
         Args:
-            argv (list of str): command line arguments.
+            argv (list): command line arguments.
 
         Keyword Args:
             fail_on_error (optional bool): Don't raise an exception on error
@@ -625,7 +625,7 @@ def print_setup_info(*info):
     """Print basic information needed by setup-env.[c]sh.
 
     Args:
-        info (list of str): list of things to print: comma-separated list
+        info (list): list of things to print: comma-separated list
             of 'csh', 'sh', or 'modules'
 
     This is in ``main.py`` to make it fast; the setup scripts need to
@@ -689,7 +689,7 @@ def main(argv=None):
     """This is the entry point for the Spack command.
 
     Args:
-        argv (list of str or None): command line arguments, NOT including
+        argv (list or None): command line arguments, NOT including
             the executable name. If None, parses from sys.argv.
     """
     # Create a parser with a simple positional argument first.  We'll
diff --git a/lib/spack/spack/mixins.py b/lib/spack/spack/mixins.py
index 596aabebec..7a3c03d4e3 100644
--- a/lib/spack/spack/mixins.py
+++ b/lib/spack/spack/mixins.py
@@ -19,7 +19,8 @@ else:
 import llnl.util.filesystem
 
 __all__ = [
-    'filter_compiler_wrappers'
+    'filter_compiler_wrappers',
+    'PackageMixinsMeta',
 ]
 
 
diff --git a/lib/spack/spack/modules/lmod.py b/lib/spack/spack/modules/lmod.py
index 38b1dd1705..0dcd78c20c 100644
--- a/lib/spack/spack/modules/lmod.py
+++ b/lib/spack/spack/modules/lmod.py
@@ -30,7 +30,7 @@ def configuration(module_set_name):
     return config
 
 
-#: Caches the configuration {spec_hash: configuration}
+# Caches the configuration {spec_hash: configuration}
 configuration_registry = {}  # type: Dict[str, Any]
 
 
diff --git a/lib/spack/spack/modules/tcl.py b/lib/spack/spack/modules/tcl.py
index 8b5e823e5e..ee6e31a7ee 100644
--- a/lib/spack/spack/modules/tcl.py
+++ b/lib/spack/spack/modules/tcl.py
@@ -29,7 +29,7 @@ def configuration(module_set_name):
     return config
 
 
-#: Caches the configuration {spec_hash: configuration}
+# Caches the configuration {spec_hash: configuration}
 configuration_registry = {}  # type: Dict[str, Any]
 
 
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
index e3299b3bdc..2f63af1377 100644
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -465,7 +465,7 @@ def test_log_pathname(test_stage, spec):
 
     Args:
         test_stage (str): path to the test stage directory
-        spec (Spec): instance of the spec under test
+        spec (spack.spec.Spec): instance of the spec under test
 
     Returns:
         (str): the pathname of the test log file
@@ -725,14 +725,14 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
         """Return dict of possible dependencies of this package.
 
         Args:
-            transitive (bool, optional): return all transitive dependencies if
+            transitive (bool or None): return all transitive dependencies if
                 True, only direct dependencies if False (default True)..
-            expand_virtuals (bool, optional): expand virtual dependencies into
+            expand_virtuals (bool or None): expand virtual dependencies into
                 all possible implementations (default True)
-            deptype (str or tuple, optional): dependency types to consider
-            visited (dicct, optional): dict of names of dependencies visited so
+            deptype (str or tuple or None): dependency types to consider
+            visited (dict or None): dict of names of dependencies visited so
                 far, mapped to their immediate dependencies' names.
-            missing (dict, optional): dict to populate with packages and their
+            missing (dict or None): dict to populate with packages and their
                 *missing* dependencies.
             virtuals (set): if provided, populate with virtuals seen so far.
 
@@ -1756,7 +1756,7 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
         during install testing.
 
         Args:
-            srcs (str or list of str): relative path for files and or
+            srcs (str or list): relative path for files and or
                 subdirectories located in the staged source path that are to
                 be copied to the corresponding location(s) under the install
                 testing directory.
@@ -1803,10 +1803,10 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
 
         Args:
             exe (str): the name of the executable
-            options (str or list of str): list of options to pass to the runner
-            expected (str or list of str): list of expected output strings.
+            options (str or list): list of options to pass to the runner
+            expected (str or list): list of expected output strings.
                 Each string is a regex expected to match part of the output.
-            status (int or list of int): possible passing status values
+            status (int or list): possible passing status values
                 with 0 meaning the test is expected to succeed
             installed (bool): if ``True``, the executable must be in the
                 install prefix
@@ -2010,9 +2010,9 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
         Spack's store.
 
         Args:
-            env (EnvironmentModifications): environment modifications to be
-                applied when the package is built. Package authors can call
-                methods on it to alter the build environment.
+            env (spack.util.environment.EnvironmentModifications): environment
+                modifications to be applied when the package is built. Package authors
+                can call methods on it to alter the build environment.
         """
         legacy_fn = self._get_legacy_environment_method('setup_environment')
         if legacy_fn:
@@ -2023,9 +2023,9 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
         """Sets up the run environment for a package.
 
         Args:
-            env (EnvironmentModifications): environment modifications to be
-                applied when the package is run. Package authors can call
-                methods on it to alter the run environment.
+            env (spack.util.environment.EnvironmentModifications): environment
+                modifications to be applied when the package is run. Package authors
+                can call methods on it to alter the run environment.
         """
         legacy_fn = self._get_legacy_environment_method('setup_environment')
         if legacy_fn:
@@ -2052,11 +2052,11 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
             variable.
 
         Args:
-            env (EnvironmentModifications): environment modifications to be
-                applied when the dependent package is built. Package authors
-                can call methods on it to alter the build environment.
+            env (spack.util.environment.EnvironmentModifications): environment
+                modifications to be applied when the dependent package is built.
+                Package authors can call methods on it to alter the build environment.
 
-            dependent_spec (Spec): the spec of the dependent package
+            dependent_spec (spack.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``
@@ -2079,11 +2079,11 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
         for dependencies.
 
         Args:
-            env (EnvironmentModifications): environment modifications to be
-                applied when the dependent package is run. Package authors
-                can call methods on it to alter the build environment.
+            env (spack.util.environment.EnvironmentModifications): environment
+                modifications to be applied when the dependent package is run.
+                Package authors can call methods on it to alter the build environment.
 
-            dependent_spec (Spec): The spec of the dependent package
+            dependent_spec (spack.spec.Spec): The spec of the dependent package
                 about to be run. This allows the extendee (self) to query
                 the dependent's state. Note that *this* package's spec is
                 available as ``self.spec``
@@ -2125,7 +2125,7 @@ class PackageBase(six.with_metaclass(PackageMeta, PackageViewMixin, object)):
                 object of the dependent package. Packages can use this to set
                 module-scope variables for the dependent to use.
 
-            dependent_spec (Spec): The spec of the dependent package
+            dependent_spec (spack.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``.
diff --git a/lib/spack/spack/patch.py b/lib/spack/spack/patch.py
index 68691554f4..a273514636 100644
--- a/lib/spack/spack/patch.py
+++ b/lib/spack/spack/patch.py
@@ -28,7 +28,7 @@ def apply_patch(stage, patch_path, level=1, working_dir='.'):
     Args:
         stage (spack.stage.Stage): stage with code that will be patched
         patch_path (str): filesystem location for the patch to apply
-        level (int, optional): patch level (default 1)
+        level (int or None): patch level (default 1)
         working_dir (str): relative path *within* the stage to change to
             (default '.')
     """
diff --git a/lib/spack/spack/relocate.py b/lib/spack/spack/relocate.py
index ef1d2e9456..c6af4d96e7 100644
--- a/lib/spack/spack/relocate.py
+++ b/lib/spack/spack/relocate.py
@@ -869,7 +869,7 @@ def is_relocatable(spec):
     """Returns True if an installed spec is relocatable.
 
     Args:
-        spec (Spec): spec to be analyzed
+        spec (spack.spec.Spec): spec to be analyzed
 
     Returns:
         True if the binaries of an installed spec
diff --git a/lib/spack/spack/solver/asp.py b/lib/spack/spack/solver/asp.py
index bb83fd4b5c..2fb20d914a 100644
--- a/lib/spack/spack/solver/asp.py
+++ b/lib/spack/spack/solver/asp.py
@@ -679,14 +679,14 @@ class SpackSolverSetup(object):
         """Generate facts for a dependency or virtual provider condition.
 
         Arguments:
-            required_spec (Spec): the spec that triggers this condition
-            imposed_spec (optional, Spec): the sepc with constraints that
+            required_spec (spack.spec.Spec): the spec that triggers this condition
+            imposed_spec (spack.spec.Spec or None): the sepc with constraints that
                 are imposed when this condition is triggered
-            name (optional, str): name for `required_spec` (required if
+            name (str or None): name for `required_spec` (required if
                 required_spec is anonymous, ignored if not)
 
         Returns:
-            (int): id of the condition created by this function
+            int: id of the condition created by this function
         """
         named_cond = required_spec.copy()
         named_cond.name = named_cond.name or name
@@ -922,7 +922,7 @@ class SpackSolverSetup(object):
         """Return a list of clauses for a spec mandates are true.
 
         Arguments:
-            spec (Spec): the spec to analyze
+            spec (spack.spec.Spec): the spec to analyze
             body (bool): if True, generate clauses to be used in rule bodies
                 (final values) instead of rule heads (setters).
             transitive (bool): if False, don't generate clauses from
diff --git a/lib/spack/spack/spec.py b/lib/spack/spack/spec.py
index 934d3317fd..af282e4425 100644
--- a/lib/spack/spack/spec.py
+++ b/lib/spack/spack/spec.py
@@ -122,7 +122,9 @@ else:
 
 
 __all__ = [
+    'CompilerSpec',
     'Spec',
+    'SpecParser',
     'parse',
     'SpecParseError',
     'DuplicateDependencyError',
@@ -143,7 +145,9 @@ __all__ = [
     'AmbiguousHashError',
     'InvalidHashError',
     'NoSuchHashError',
-    'RedundantSpecError']
+    'RedundantSpecError',
+    'SpecDeprecatedError',
+]
 
 #: Valid pattern for an identifier in Spack
 identifier_re = r'\w[\w-]*'
@@ -1495,7 +1499,7 @@ class Spec(object):
         """Utility method for computing different types of Spec hashes.
 
         Arguments:
-            hash (SpecHashDescriptor): type of hash to generate.
+            hash (spack.hash_types.SpecHashDescriptor): type of hash to generate.
         """
         # TODO: curently we strip build dependencies by default.  Rethink
         # this when we move to using package hashing on all specs.
@@ -1513,7 +1517,7 @@ class Spec(object):
         in the supplied attribute on this spec.
 
         Arguments:
-            hash (SpecHashDescriptor): type of hash to generate.
+            hash (spack.hash_types.SpecHashDescriptor): type of hash to generate.
         """
         if not hash.attr:
             return self._spec_hash(hash)[:length]
@@ -1615,7 +1619,7 @@ class Spec(object):
         hashes).
 
         Arguments:
-            hash (SpecHashDescriptor) type of hash to generate.
+            hash (spack.hash_types.SpecHashDescriptor) type of hash to generate.
          """
         d = syaml.syaml_dict()
 
@@ -2987,7 +2991,7 @@ class Spec(object):
             spec (Spec): spec to be analyzed
 
         Raises:
-            UnknownVariantError: on the first unknown variant found
+            spack.variant.UnknownVariantError: on the first unknown variant found
         """
         pkg_cls = spec.package_class
         pkg_variants = pkg_cls.variants
@@ -4437,6 +4441,7 @@ _lexer = SpecLexer()
 
 
 class SpecParser(spack.parse.Parser):
+    """Parses specs."""
 
     def __init__(self, initial_spec=None):
         """Construct a new SpecParser.
diff --git a/lib/spack/spack/stage.py b/lib/spack/spack/stage.py
index 1ca2ed5637..e4d34a20df 100644
--- a/lib/spack/spack/stage.py
+++ b/lib/spack/spack/stage.py
@@ -565,8 +565,9 @@ class Stage(object):
         """Perform a fetch if the resource is not already cached
 
         Arguments:
-            mirror (MirrorCache): the mirror to cache this Stage's resource in
-            stats (MirrorStats): this is updated depending on whether the
+            mirror (spack.caches.MirrorCache): the mirror to cache this Stage's
+                resource in
+            stats (spack.mirror.MirrorStats): this is updated depending on whether the
                 caching operation succeeded or failed
         """
         if isinstance(self.default_fetcher, fs.BundleFetchStrategy):
@@ -835,7 +836,7 @@ def get_checksums_for_versions(
     Args:
         url_dict (dict): A dictionary of the form: version -> URL
         name (str): The name of the package
-        first_stage_function (callable): function that takes a Stage and a URL;
+        first_stage_function (typing.Callable): function that takes a Stage and a URL;
             this is run on the stage of the first URL downloaded
         keep_stage (bool): whether to keep staging area when command completes
         batch (bool): whether to ask user how many versions to fetch (false)
diff --git a/lib/spack/spack/test/installer.py b/lib/spack/spack/test/installer.py
index 76dddc9a4f..485fbb1536 100644
--- a/lib/spack/spack/test/installer.py
+++ b/lib/spack/spack/test/installer.py
@@ -65,7 +65,7 @@ def create_build_task(pkg, install_args={}):
     Create a built task for the given (concretized) package
 
     Args:
-        pkg (PackageBase): concretized package associated with the task
+        pkg (spack.package.PackageBase): concretized package associated with the task
         install_args (dict): dictionary of kwargs (or install args)
 
     Return:
@@ -80,10 +80,10 @@ def create_installer(installer_args):
     Create an installer using the concretized spec for each arg
 
     Args:
-        installer_args (list of tuples): the list of (spec name, kwargs) tuples
+        installer_args (list): the list of (spec name, kwargs) tuples
 
     Return:
-        installer (PackageInstaller): the associated package installer
+        spack.installer.PackageInstaller: the associated package installer
     """
     const_arg = [(spec.package, kwargs) for spec, kwargs in installer_args]
     return inst.PackageInstaller(const_arg)
@@ -93,11 +93,11 @@ def installer_args(spec_names, kwargs={}):
     """Return a the installer argument with each spec paired with kwargs
 
     Args:
-        spec_names (list of str): list of spec names
+        spec_names (list): list of spec names
         kwargs (dict or None): install arguments to apply to all of the specs
 
     Returns:
-        list of (spec, kwargs): the installer constructor argument
+        list: list of (spec, kwargs), the installer constructor argument
     """
     arg = []
     for name in spec_names:
diff --git a/lib/spack/spack/url.py b/lib/spack/spack/url.py
index 770c5bd4c0..bfe74318f6 100644
--- a/lib/spack/spack/url.py
+++ b/lib/spack/spack/url.py
@@ -417,11 +417,11 @@ def parse_version_offset(path):
         path (str): The filename or URL for the package
 
     Returns:
-        tuple of (Version, int, int, int, str): A tuple containing:
+        tuple: A tuple containing:
             version of the package,
             first index of version,
             length of version string,
-            the index of the matching regex
+            the index of the matching regex,
             the matching regex
 
     Raises:
@@ -632,11 +632,11 @@ def parse_name_offset(path, v=None):
         v (str): The version of the package
 
     Returns:
-        tuple of (str, int, int, int, str): A tuple containing:
+        tuple: A tuple containing:
             name of the package,
             first index of name,
             length of name,
-            the index of the matching regex
+            the index of the matching regex,
             the matching regex
 
     Raises:
@@ -774,9 +774,7 @@ def parse_name_and_version(path):
         path (str): The filename or URL for the package
 
     Returns:
-        tuple of (str, Version)A tuple containing:
-            The name of the package
-            The version of the package
+        tuple: a tuple containing the package (name, version)
 
     Raises:
         UndetectableVersionError: If the URL does not match any regexes
diff --git a/lib/spack/spack/user_environment.py b/lib/spack/spack/user_environment.py
index 005c6351b5..23fb6529d8 100644
--- a/lib/spack/spack/user_environment.py
+++ b/lib/spack/spack/user_environment.py
@@ -18,7 +18,7 @@ def prefix_inspections(platform):
     """Get list of prefix inspections for platform
 
     Arguments:
-        platform (string): the name of the platform to consider. The platform
+        platform (str): the name of the platform to consider. The platform
             determines what environment variables Spack will use for some
             inspections.
 
diff --git a/lib/spack/spack/util/editor.py b/lib/spack/spack/util/editor.py
index 400c4eb63a..02e59a45f0 100644
--- a/lib/spack/spack/util/editor.py
+++ b/lib/spack/spack/util/editor.py
@@ -64,7 +64,7 @@ def editor(*args, **kwargs):
     searching the full list above, we'll raise an error.
 
     Arguments:
-        args (list of str): args to pass to editor
+        args (list): args to pass to editor
 
     Optional Arguments:
         _exec_func (function): invoke this function instead of ``os.execv()``
diff --git a/lib/spack/spack/util/environment.py b/lib/spack/spack/util/environment.py
index f33e3c0b8f..073f60334e 100644
--- a/lib/spack/spack/util/environment.py
+++ b/lib/spack/spack/util/environment.py
@@ -623,7 +623,7 @@ class EnvironmentModifications(object):
 
         Args:
             filename (str): the file to be sourced
-            *arguments (list of str): arguments to pass on the command line
+            *arguments (list): arguments to pass on the command line
 
         Keyword Args:
             shell (str): the shell to use (default: ``bash``)
@@ -867,7 +867,7 @@ def inspect_path(root, inspections, exclude=None):
             modifications are not performed immediately, but stored in a
             command object that is returned to client
 
-        exclude (callable): optional callable. If present it must accept an
+        exclude (typing.Callable): optional callable. If present it must accept an
             absolute path and return True if it should be excluded from the
             inspection
 
@@ -920,7 +920,7 @@ def preserve_environment(*variables):
     explicitly unset on exit.
 
     Args:
-        variables (list of str): list of environment variables to be preserved
+        variables (list): list of environment variables to be preserved
     """
     cache = {}
     for var in variables:
@@ -1031,9 +1031,9 @@ def sanitize(environment, blacklist, whitelist):
 
     Args:
         environment (dict): input dictionary
-        blacklist (list of str): literals or regex patterns to be
+        blacklist (list): literals or regex patterns to be
             blacklisted
-        whitelist (list of str): literals or regex patterns to be
+        whitelist (list): literals or regex patterns to be
             whitelisted
     """
 
diff --git a/lib/spack/spack/util/executable.py b/lib/spack/spack/util/executable.py
index 084ca48147..1074a96cf7 100644
--- a/lib/spack/spack/util/executable.py
+++ b/lib/spack/spack/util/executable.py
@@ -297,7 +297,7 @@ def which(*args, **kwargs):
         *args (str): One or more executables to search for
 
     Keyword Arguments:
-        path (:func:`list` or str): The path to search. Defaults to ``PATH``
+        path (list or str): The path to search. Defaults to ``PATH``
         required (bool): If set to True, raise an error if executable not found
 
     Returns:
diff --git a/lib/spack/spack/util/imp/imp_importer.py b/lib/spack/spack/util/imp/imp_importer.py
index a9b5cd641a..d41d28928b 100644
--- a/lib/spack/spack/util/imp/imp_importer.py
+++ b/lib/spack/spack/util/imp/imp_importer.py
@@ -28,11 +28,11 @@ def load_source(full_name, path, prepend=None):
     Args:
         full_name (str): full name of the module to be loaded
         path (str): path to the file that should be loaded
-        prepend (str, optional): some optional code to prepend to the
+        prepend (str or None): some optional code to prepend to the
             loaded module; e.g., can be used to inject import statements
 
     Returns:
-        (ModuleType): the loaded module
+        the loaded module
     """
     with import_lock():
         if prepend is None:
diff --git a/lib/spack/spack/util/imp/importlib_importer.py b/lib/spack/spack/util/imp/importlib_importer.py
index 4c8a2673e5..161e278e90 100644
--- a/lib/spack/spack/util/imp/importlib_importer.py
+++ b/lib/spack/spack/util/imp/importlib_importer.py
@@ -37,11 +37,11 @@ def load_source(full_name, path, prepend=None):
     Args:
         full_name (str): full name of the module to be loaded
         path (str): path to the file that should be loaded
-        prepend (str, optional): some optional code to prepend to the
+        prepend (str or None): some optional code to prepend to the
             loaded module; e.g., can be used to inject import statements
 
     Returns:
-        (ModuleType): the loaded module
+        the loaded module
     """
     # use our custom loader
     loader = PrependFileLoader(full_name, path, prepend)
diff --git a/lib/spack/spack/util/log_parse.py b/lib/spack/spack/util/log_parse.py
index ccfde6d279..11692b0afb 100644
--- a/lib/spack/spack/util/log_parse.py
+++ b/lib/spack/spack/util/log_parse.py
@@ -20,7 +20,7 @@ def parse_log_events(stream, context=6, jobs=None, profile=False):
     """Extract interesting events from a log file as a list of LogEvent.
 
     Args:
-        stream (str or fileobject): build log name or file object
+        stream (str or typing.IO): build log name or file object
         context (int): lines of context to extract around each log event
         jobs (int): number of jobs to parse with; default ncpus
         profile (bool): print out profile information for parsing
@@ -60,7 +60,7 @@ def make_log_context(log_events, width=None):
     """Get error context from a log file.
 
     Args:
-        log_events (list of LogEvent): list of events created by
+        log_events (list): list of events created by
             ``ctest_log_parser.parse()``
         width (int or None): wrap width; ``0`` for no limit; ``None`` to
             auto-size for terminal
diff --git a/lib/spack/spack/util/package_hash.py b/lib/spack/spack/util/package_hash.py
index 05d7abe056..bb9ad40e45 100644
--- a/lib/spack/spack/util/package_hash.py
+++ b/lib/spack/spack/util/package_hash.py
@@ -49,10 +49,10 @@ class RemoveDirectives(ast.NodeTransformer):
         callbacks are sometimes represented).
 
         Args:
-            node (AST): the AST node being checked
+            node (ast.AST): the AST node being checked
 
         Returns:
-            (bool): ``True`` if the node represents a known directive,
+            bool: ``True`` if the node represents a known directive,
                 ``False`` otherwise
         """
         return (isinstance(node, ast.Expr) and
diff --git a/lib/spack/spack/util/pattern.py b/lib/spack/spack/util/pattern.py
index 655172886b..0ddc51a165 100644
--- a/lib/spack/spack/util/pattern.py
+++ b/lib/spack/spack/util/pattern.py
@@ -41,7 +41,7 @@ def composite(interface=None, method_list=None, container=list):
         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
+        method_list (list): names of methods that should be part
             of the composite
         container (MutableSequence): container for the composite object
             (default = list).  Must fulfill the MutableSequence
diff --git a/lib/spack/spack/util/string.py b/lib/spack/spack/util/string.py
index 6137c32d5a..e132404e18 100644
--- a/lib/spack/spack/util/string.py
+++ b/lib/spack/spack/util/string.py
@@ -41,7 +41,7 @@ def plural(n, singular, plural=None, show_n=True):
     Arguments:
         n (int): number of things there are
         singular (str): singular form of word
-        plural (str, optional): optional plural form, for when it's not just
+        plural (str or None): optional plural form, for when it's not just
             singular + 's'
         show_n (bool): whether to include n in the result string (default True)
 
diff --git a/lib/spack/spack/util/web.py b/lib/spack/spack/util/web.py
index 4787e33dd6..34140ed74a 100644
--- a/lib/spack/spack/util/web.py
+++ b/lib/spack/spack/util/web.py
@@ -367,7 +367,7 @@ def spider(root_urls, depth=0, concurrency=32):
     up to <depth> levels of links from each root.
 
     Args:
-        root_urls (str or list of str): root urls used as a starting point
+        root_urls (str or list): root urls used as a starting point
             for spidering
         depth (int): level of recursion into links
         concurrency (int): number of simultaneous requests that can be sent
diff --git a/lib/spack/spack/variant.py b/lib/spack/spack/variant.py
index 9b7d8779fe..3badd30c20 100644
--- a/lib/spack/spack/variant.py
+++ b/lib/spack/spack/variant.py
@@ -94,8 +94,8 @@ class Variant(object):
         exception if any error is found.
 
         Args:
-            vspec (VariantSpec): instance to be validated
-            pkg (Package): the package that required the validation,
+            vspec (Variant): instance to be validated
+            pkg (spack.package.Package): the package that required the validation,
                 if available
 
         Raises:
@@ -254,7 +254,7 @@ class AbstractVariant(object):
         the variant.
 
         Returns:
-            tuple of str: values stored in the variant
+            tuple: values stored in the variant
         """
         return self._value
 
@@ -296,7 +296,7 @@ class AbstractVariant(object):
         """Returns an instance of a variant equivalent to self
 
         Returns:
-            any variant type: a copy of self
+            AbstractVariant: a copy of self
 
         >>> a = MultiValuedVariant('foo', True)
         >>> b = a.copy()
@@ -667,7 +667,7 @@ class DisjointSetsOfValues(Sequence):
     and therefore no other set can contain the item ``'none'``.
 
     Args:
-        *sets (list of tuples): mutually exclusive sets of values
+        *sets (list): mutually exclusive sets of values
     """
 
     _empty_set = set(('none',))