Merge pull request #95 from hpcugent/develop

update to docs release 20150306.03 for EasyBuild v2.0.0

docs/Changelog.rst

@@ -3,17 +3,36 @@
 Changelog for EasyBuild documentation
 -------------------------------------
 
+* **release 20150306.03** (`Mar 6th 2015`): add release notes for EasyBuild v2.0.0 (see :ref:`release_notes`)
+* **release 20150306.02** (`Mar 6th 2015`):
+
+  * add documentation on GitHub integration features (see :ref:`integration_with_github`), mainly ``--from-pr`` (see :ref:`from_pr`)
+  * document locations where (specified) easyconfig files are being searched for (see :ref:`specifying_easyconfigs`)
+* **release 20150306.01** (`Mar 6th 2015`):
+
+  * add documentation on removed functionality (see :ref:`removed_functionality`)
+  * clean up documentation on deprecated functionality (see :ref:`deprecated`)
+  * add documentation on provided scripts, in particular ``fix-broken-easyconfigs.py`` (see :ref:`useful_scripts`)
+* **release 20150302.01** (`Mar 2nd 2015`): update/cleanup documentation on :ref:`alt_inst_methods`
+* **release 20150227.02** (`Feb 27th 2015`): add documentation on the EasyBuild unit test suites, see :ref:`unit_tests`
+* **release 20150227.01** (`Feb 27th 2015`): enhance documentation w.r.t. to (optional dependencies), see :ref:`installation`
+* **release 20150220.01** (`Feb 20th 2015`):
+
+  * document new advanced bootstrapping options: skipping stage 0 and providing source tarballs (see :ref:`installation`)
+* **release 20150219.01** (`Feb 19th 2015`): first updates for EasyBuild v2.0.0
+
+  * extend section on (default) EasyBuild configuration files to also cover ``$XDG_CONFIG_DIRS`` (see :ref:`configuration_file:`)
 * **release 20150205.01** (`Feb 5th 2015`): include information on deprecated functionality in (generic) easyblocks (see :ref:`deprecated`)
 * **release 20150126.01** (`Jan 26th 2015`):
 
   * fix ``pip`` installation prefix option (:ref:`alt_inst_methods`)
   * clarify need to have modules tool binary available in ``$PATH`` (:ref:`installation`)
 * **release 20150112.01** (`Jan 12th 2015`): mention need to escape ``%`` when setting log file format via config file (see :ref:`logfile_format`)
 * **release 20150107.01** (`Jan 7th 2015`): document behaviour of `dummy` toolchain (:ref:`dummy_toolchain`)
-* **release 20141219.01** (`Dec 19th 2014`): add release notes for EasyBuild v1.16.1
-* **release 20141218.01** (`Dec 18th 2014`): add release notes for EasyBuild v1.16.0
+* **release 20141219.01** (`Dec 19th 2014`): add release notes for EasyBuild v1.16.1 (see :ref:`release_notes`)
+* **release 20141218.01** (`Dec 18th 2014`): add release notes for EasyBuild v1.16.0 (see :ref:`release_notes`)
 * **release 20141217.01** (`Dec 17th 2014`): document deprecated functionality in EasyBuild v1.x (:ref:`deprecated`)
-* **release 20141204.02** (`Dec 4th 2014`): add EasyBuild release notes
+* **release 20141204.02** (`Dec 4th 2014`): add EasyBuild release notes (see :ref:`release_notes`)
 * **release 20141204.01** (`Dec 4th 2014`): updates for EasyBuild v1.16.0
 
   * document details w.r.t. (controlling of) robot search path, incl. ``--robot-paths`` (:ref:`using_the_easybuild_command_line`)

docs/Configuration.rst

@@ -67,28 +67,53 @@ For more details w.r.t. each of the supported configuration types, see below.
 
 .. _configuration_file:
 
-Configuration file
-~~~~~~~~~~~~~~~~~~
+Configuration file(s)
+~~~~~~~~~~~~~~~~~~~~~
 
 .. _list_of_configuration_files:
 
 List of used configuration files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The set of configuration files that will be used by EasyBuild is
-determined in the following order of preference:
+The list of configuration files that will be used by EasyBuild is determined in the following order of preference:
 
-* the path(s) specified via **command line argument** ``--configfiles``
+* the path(s) specified via the **command line argument** ``--configfiles``
 * the path(s) specified via the ``$EASYBUILD_CONFIGFILES`` **environment variable**
-* the **default path** for the EasyBuild configuration file, i.e.
-   ``$XDG_CONFIG_HOME/easybuild/config.cfg`` (``$XDG_CONFIG_HOME`` defaults to ``$HOME/.config``).
+* the **default paths** for EasyBuild configuration files
+
+.. _default_configuration_files:
+
+Default configuration files
++++++++++++++++++++++++++++
+
+By default, EasyBuild will use existing configuration files at the following paths:
+
+* ``$dir/easybuild.d/*.cfg``, for each directory ``$dir`` listed in ``$XDG_CONFIG_DIRS`` (where ``$XDG_CONFIG_DIRS``
+  defaults to ``/etc``)
+* ``$XDG_CONFIG_HOME/easybuild/config.cfg`` (where ``$XDG_CONFIG_HOME`` defaults to ``$HOME/.config``)
+
+Hence, if ``$XDG_CONFIG_HOME`` and ``$XDG_CONFIG_DIRS`` are not defined, EasyBuild will only consider default
+configuration files at ``/etc/easybuild.d/*.cfg`` and ``$HOME/.config/easybuild/config.cfg``.
+
+The configuration file located in ``$XDG_CONFIG_HOME`` will be listed *after* the ones obtained via ``$XDG_CONFIG_DIRS``,
+such that user-defined configuration settings have preference over system defaults.
+
+Multiple configuration files
+++++++++++++++++++++++++++++
+
+If multiple configuration files are listed via a mechanism listed above, the settings in the last
+configuration file have preference over the others.
+
+Each available configuration file will be used, and the configuration settings specified in these files
+will be retained according to the order of preference as indicated above: settings in configuration files specfied via
+``--configfiles`` override those in configuration files specified via ``$EASYBUILD_CONFIGFILES``, which in turns override
+settings in default configuration files.
 
-Note that each available configuration file will be used, and that the
-configuration settings specified in these files will be retained according to the order of preference as indicated above.
+Ignored configuration files
++++++++++++++++++++++++++++
 
-On top of this, the command line argument ``--ignoreconfigfiles``
-allows to specify configuration files that should be *ignored* by EasyBuild
-(regardless of whether they are specified via any of the options above).
+On top of this, the ``--ignoreconfigfiles`` configuration option allows to specify configuration files that should be
+*ignored* by EasyBuild (regardless of whether they are specified via any of the options above).
 
 
 Configuration file format