Consistent docs and usage of env mod methods (#3351)

2 files changed, 61 insertions, 81 deletions

diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 211e72158c..b794bb2581 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -1523,23 +1523,23 @@ properties to be used by dependents.
 
 The function declaration should look like this:
 
-.. code-block:: python
-
-   class Qt(Package):
-       ...
-       def setup_dependent_environment(self, module, spec, dep_spec):
-           """Dependencies of Qt find it using the QTDIR environment variable."""
-           os.environ['QTDIR'] = self.prefix
+.. literalinclude:: ../../../var/spack/repos/builtin/packages/qt/package.py
+   :pyobject: Qt.setup_dependent_environment
+   :linenos:
 
 Here, the Qt package sets the ``QTDIR`` environment variable so that
 packages that depend on a particular Qt installation will find it.
 
 The arguments to this function are:
 
-* **module**: the module of the dependent package, where global
-  properties can be assigned.
-* **spec**: the spec of the *dependency package* (the one the function is called on).
-* **dep_spec**: the spec of the dependent package (i.e. dep_spec depends on spec).
+* **spack_env**: List of environment modifications to be applied when
+  the dependent package is built within Spack.
+* **run_env**: List of environment modifications to be applied when
+  the dependent package is run outside of Spack. These are added to the
+  resulting module file.
+* **dependent_spec**: The spec of the dependent package about to be
+  built. This allows the extendee (self) to query the dependent's state.
+  Note that *this* package's spec is available as ``self.spec``.
 
 A good example of using these is in the Python package:
 
@@ -2805,11 +2805,8 @@ the one passed to install, only the MPI implementations all set some
 additional properties on it to help you out.  E.g., in mvapich2, you'll
 find this:
 
-.. code-block:: python
-
-    def setup_dependent_package(self, module, dep_spec):
-        self.spec.mpicc  = join_path(self.prefix.bin, 'mpicc')
-        # … etc …
+.. literalinclude:: ../../../var/spack/repos/builtin/packages/mvapich2/package.py
+   :pyobject: Mvapich2.setup_dependent_package
 
 That code allows the mvapich2 package to associate an ``mpicc`` property
 with the ``mvapich2`` node in the DAG, so that dependents can access it.
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
index 8889de7576..80d65bd739 100644
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -1393,32 +1393,29 @@ class PackageBase(object):
     def setup_environment(self, spack_env, run_env):
         """Set up the compile and runtime environments for a package.
 
-        `spack_env` and `run_env` are `EnvironmentModifications`
-        objects.  Package authors can call methods on them to alter
+        ``spack_env`` and ``run_env`` are ``EnvironmentModifications``
+        objects. Package authors can call methods on them to alter
         the environment within Spack and at runtime.
 
-        Both `spack_env` and `run_env` are applied within the build
-        process, before this package's `install()` method is called.
+        Both ``spack_env`` and ``run_env`` are applied within the build
+        process, before this package's ``install()`` method is called.
 
-        Modifications in `run_env` will *also* be added to the
+        Modifications in ``run_env`` will *also* be added to the
         generated environment modules for this package.
 
         Default implementation does nothing, but this can be
         overridden if the package needs a particular environment.
 
-        Examples:
-
-            1. Qt extensions need `QTDIR` set.
-
-        Args:
-            spack_env (EnvironmentModifications): list of
-                modifications to be applied when this package is built
-                within Spack.
+        Example:
 
-            run_env (EnvironmentModifications): list of environment
-                changes to be applied when this package is run outside
-                of Spack.
+        1. Qt extensions need ``QTDIR`` set.
 
+        :param EnvironmentModifications spack_env: List of environment
+            modifications to be applied when this package is built
+            within Spack.
+        :param EnvironmentModifications run_env: List of environment
+            modifications to be applied when this package is run outside
+            of Spack. These are added to the resulting module file.
         """
         pass
 
@@ -1431,32 +1428,26 @@ class PackageBase(object):
         others that follow the extension model a way to implement
         common environment or compile-time settings for dependencies.
 
-        By default, this delegates to ``self.setup_environment()``
+        This is useful if there are some common steps to installing
+        all extensions for a certain package.
 
         Example:
 
-            1. Installing python modules generally requires
-               `PYTHONPATH` to point to the lib/pythonX.Y/site-packages
-               directory in the module's install prefix.  This could
-               set that variable.
-
-        Args:
-
-            spack_env (EnvironmentModifications): list of
-                modifications to be applied when the dependent package
-                is bulit within Spack.
-
-            run_env (EnvironmentModifications): list of environment
-                changes to be applied when the dependent package is
-                run outside of Spack.
-
-            dependent_spec (Spec): The spec of the dependent package
-                about to be built. This allows the extendee (self) to
-                query the dependent's state. Note that *this*
-                package's spec is available as `self.spec`.
-
-        This is useful if there are some common steps to installing
-        all extensions for a certain package.
+        1. Installing python modules generally requires ``PYTHONPATH`` to point
+           to the ``lib/pythonX.Y/site-packages`` directory in the module's
+           install prefix. This method could be used to set that variable.
+
+        :param EnvironmentModifications spack_env: List of environment
+            modifications to be applied when the dependent package is
+            built within Spack.
+        :param EnvironmentModifications run_env: List of environment
+            modifications to be applied when the dependent package is
+            run outside of Spack. These are added to the resulting
+            module file.
+        :param Spec dependent_spec: The spec of the dependent package
+            about to be built. This allows the extendee (self) to query
+            the dependent's state. Note that *this* package's spec is
+            available as ``self.spec``.
         """
         pass
 
@@ -1470,37 +1461,29 @@ class PackageBase(object):
         its extensions. This is useful if there are some common steps
         to installing all extensions for a certain package.
 
-        Example :
-
-            1. Extensions often need to invoke the `python`
-               interpreter from the Python installation being
-               extended.  This routine can put a 'python' Executable
-               object in the module scope for the extension package to
-               simplify extension installs.
-
-            2. MPI compilers could set some variables in the
-               dependent's scope that point to `mpicc`, `mpicxx`,
-               etc., allowing them to be called by common names
-               regardless of which MPI is used.
-
-            3. BLAS/LAPACK implementations can set some variables
-               indicating the path to their libraries, since these
-               paths differ by BLAS/LAPACK implementation.
+        Examples:
 
-        Args:
+        1. Extensions often need to invoke the ``python`` interpreter
+           from the Python installation being extended. This routine
+           can put a ``python()`` Executable object in the module scope
+           for the extension package to simplify extension installs.
 
-            module (module): The Python `module` object of the
-                dependent package. Packages can use this to set
-                module-scope variables for the dependent to use.
+        2. MPI compilers could set some variables in the dependent's
+           scope that point to ``mpicc``, ``mpicxx``, etc., allowing
+           them to be called by common name regardless of which MPI is used.
 
-            dependent_spec (Spec): The spec of the dependent package
-                about to be built. This allows the extendee (self) to
-                query the dependent's state.  Note that *this*
-                package's spec is available as `self.spec`.
+        3. BLAS/LAPACK implementations can set some variables
+           indicating the path to their libraries, since these
+           paths differ by BLAS/LAPACK implementation.
 
-        This is useful if there are some common steps to installing
-        all extensions for a certain package.
+        :param spack.package.PackageBase.module module: The Python ``module``
+            object of the dependent package. Packages can use this to set
+            module-scope variables for the dependent to use.
 
+        :param Spec dependent_spec: The spec of the dependent package
+            about to be built. This allows the extendee (self) to
+            query the dependent's state.  Note that *this*
+            package's spec is available as ``self.spec``.
         """
         pass