add documentation on deprecated easyconfigs/toolchains

docs/Changelog.rst

@@ -5,6 +5,7 @@ Changelog for EasyBuild documentation
 
 (for EasyBuild release notes, see :ref:`release_notes`)
 
+* **release 20181114.01** (`Nov 14th 2018`): add documentation on deprecated easyconfigs & toolchains (:ref:`deprecated_easyconfigs`)
 * **release 20181104.01** (`Nov 4th 2018`): update ``--job`` documentation to also cover ``Slurm`` job backend (see :ref:`submitting_jobs`)
 * **release 20181018.01** (`Oct 18th 2018`): update release notes for EasyBuild v3.7.1 (see :ref:`release_notes_eb371`)
 * **release 20180925.01** (`Sep 25th 2018`): update release notes for EasyBuild v3.7.0 (see :ref:`release_notes_eb370`)

docs/Deprecated-easyconfigs.rst

@@ -0,0 +1,57 @@
+.. _deprecated_easyconfigs:
+
+Deprecated easyconfigs
+======================
+
+Since EasyBuild v3.8.0, individual easyconfig files or particular (versions of) toolchains can be marked as deprecated.
+
+.. contents::
+    :depth: 3
+    :backlinks: none
+
+
+.. _deprecated_easyconfigs_symptoms:
+
+Symptoms
+--------
+
+Using an easyconfig file or toolchain that was marked as deprecated results in a warning message like:
+
+::
+
+  WARNING: Deprecated functionality, will no longer work in v4.0: easyconfig file '/home/example/test.eb' is marked as deprecated:
+  This is an example message explaining why the easyconfig file was deprecated.
+  (see also http://easybuild.readthedocs.org/en/latest/Deprecated-easyconfigs.html)
+
+Or, in case you are trying to use an easyconfig file or toolchain that was marked deprecated in a previous major version
+of EasyBuild:
+
+::
+
+  ERROR: Failed to process easyconfig /home/example/test.eb: DEPRECATED (since v4.0) functionality used: easyconfig file '/home/example/test.eb' is marked as deprecated:
+  This is an example message explaining why the easyconfig file was deprecated.
+  (see also http://easybuild.readthedocs.org/en/latest/Deprecated-easyconfigs.html)
+
+
+.. _deprecated_easyconfigs_why:
+
+Reasons for deprecation
+-----------------------
+
+There are several possible reasons why a particular easyconfig file or toolchain was deprecated, some of which include:
+
+* old/obsolete versions of software or toolchain components
+* toolchains that are superseded by other toolchains
+* known installation problems that are hard to resolve (or not worth the effort to resolve)
+
+
+.. _deprecated_easyconfigs_implications:
+
+Implications
+------------
+
+Easyconfig files that are deprecated or which use a deprecated toolchain are *not actively maintained*,
+and are *no longer included in the EasyBuild regression test* (which means they may be broken by recent changes
+to the EasyBuild framework or relevant easyblocks).
+
+In a future major version of EasyBuild, these easyconfig files will be archived (see also :ref:`archived_easyconfigs`).

docs/conf.py

@@ -41,9 +41,9 @@
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '3.8.0'  # this is meant to reference the version of EasyBuild
+version = '3.8.0dev'  # this is meant to reference the version of EasyBuild
 # The full version, including alpha/beta/rc tags.
-release = '20181104.01'  # this is meant to reference the version of the documentation itself
+release = '20181114.01'  # this is meant to reference the version of the documentation itself
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -75,6 +75,9 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# don't use (Python) highlighting by default
+highlight_language = 'none'
+
 # Options for HTML output
 # -----------------------
 

docs/index.rst

@@ -87,6 +87,7 @@ Other topics
     Code_style
     Unit-tests
     Useful-scripts
+    Deprecated-easyconfigs
     Deprecated-functionality
     Removed-functionality
     Maintainers