Deprecate Stampede2Environment (#798)

* depr: Stampede2Environment

Also set up system for deprecating environments.

* doc: Update changelog

* doc: Document Stampede2's deprecation.

* fix: get_environment add return statement

* doc: Use Sphinx's build-in deprecation warning system.

changelog.txt

@@ -19,6 +19,7 @@ Added
 
 Changed
 +++++++
+- The Stampede2 environment is deprecated (#798).
 - Show the "Using environment configuration:" message only in verbose output (#776).
 
 Fixed

flow/environment.py

@@ -35,6 +35,7 @@
 from .scheduling.pbs import PBSScheduler
 from .scheduling.simple_scheduler import SimpleScheduler
 from .scheduling.slurm import SlurmScheduler
+from .util.misc import _deprecated_warning
 from .util.template_filters import calc_num_nodes, calc_tasks
 
 logger = logging.getLogger(__name__)
@@ -655,6 +656,44 @@ def get_environment(test=False):
     environment where the :meth:`~.ComputeEnvironment.is_present` method
     returns True.
 
+    Note
+    ----
+    Environments can be set to raise FutureWarnings by setting a class attribute
+    ``_deprecated`` to ``True``.
+
+    Parameters
+    ----------
+    test : bool
+        Whether to return the TestEnvironment. (Default value = False)
+    import_configured : bool
+        Whether to import environments specified in the flow configuration.
+        (Default value = True)
+
+    Returns
+    -------
+    :class:`~.ComputeEnvironment`
+        The detected environment class.
+
+    """
+    env = _get_environment(test)
+    if getattr(env, "_deprecated", False):
+        _deprecated_warning(
+            deprecation=str(env),
+            alternative="",
+            deprecated_in="v0.27.0",
+            removed_in="v0.28.0",
+        )
+    return env
+
+
+def _get_environment(test=False):
+    """Attempt to detect the present environment.
+
+    This function iterates through all defined :class:`~.ComputeEnvironment`
+    classes in reversed order of definition and returns the first
+    environment where the :meth:`~.ComputeEnvironment.is_present` method
+    returns True.
+
     Parameters
     ----------
     test : bool

flow/environments/xsede.py

@@ -21,9 +21,13 @@
 class Stampede2Environment(DefaultSlurmEnvironment):
     """Environment profile for the Stampede2 supercomputer.
 
+    .. deprecated:: 0.27.0
+        Stampede2Environment will be removed in 0.28.0.
+
     https://www.tacc.utexas.edu/systems/stampede2
     """
 
+    _deprecated = True
     hostname_pattern = ".*stampede2"
     template = "stampede2.sh"
     cores_per_node = 48