From b4b6f949ccb6f867fbb58412d2e92259f77772a7 Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Fri, 8 Jun 2018 16:54:18 +0100 Subject: [PATCH] doc: Add overview of how WA config merging works --- doc/source/user_reference/agenda.rst | 3 ++- doc/source/user_reference/configuration.rst | 25 +++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/doc/source/user_reference/agenda.rst b/doc/source/user_reference/agenda.rst index 5a20b729..1bac5f81 100644 --- a/doc/source/user_reference/agenda.rst +++ b/doc/source/user_reference/agenda.rst @@ -21,7 +21,8 @@ config This section is used to provide overall configuration for WA and its run. The ``config`` section of an agenda will be merged with any other configuration files provided (including the default config file) and merged with the most -specific configuration taking precedence. +specific configuration taking precedence (see :ref:`here ` for +more information. Within this section there are multiple distinct types of configuration that can be provided. diff --git a/doc/source/user_reference/configuration.rst b/doc/source/user_reference/configuration.rst index 3061380f..12b6c412 100644 --- a/doc/source/user_reference/configuration.rst +++ b/doc/source/user_reference/configuration.rst @@ -72,6 +72,31 @@ various assets when it starts. scans a very large number of locations; this may also be set to a lower value to reduce WA's memory footprint on memory-constrained hosts. +--------------------- .. include:: user_reference/runtime_parameters.rst +--------------------- + +.. _config-merging: + +Configuration Merging +--------------------- +WA configuration can come from various sources of increasing priority, as well +as being specified in a generic and specific manner. For example WA's global +config file would be considered the least specific vs the parameters of a +workload in an agenda which would be the most specific. WA has two rules for the +priority of configuration: + + - Configuration from higher priority sources overrides configuration from + lower priority sources. + - More specific configuration overrides less specific configuration. + +There is a situation where these two rules come into conflict. When a generic +configuration is given in config source of high priority and a specific +configuration is given in a config source of lower priority. In this situation +it is not possible to know the end users intention and WA will error. + +This functionality allows for defaults for plugins, targets etc. to be +configured at a global level and then seamless overridden without the need to +remove the high level configuration.