doc: Restructure

Restructure the documentation to be split into `User Information` and
`Developer Information`, and split the how to guides into their
corresponding section.

doc/source/user_information/user_reference/configuration.rst

@@ -0,0 +1,102 @@
+.. _configuration-specification:
+
+
+Configuration
+=============
+
+.. include:: user_information/user_reference/agenda.rst
+
+---------------------
+
+.. _run-configuration:
+
+Run Configuration
+------------------
+In addition to specifying run execution parameters through an agenda, the
+behaviour of WA can be modified through configuration file(s). The default
+configuration file is ``~/.workload_automation/config.yaml``  (the location can
+be changed by setting ``WA_USER_DIRECTORY`` environment variable, see
+:ref:`envvars` section below). This file will be created when you first run WA
+if it does not already exist. This file must always exist and will always be
+loaded. You can add to or override the contents of that file on invocation of
+Workload Automation by specifying an additional configuration file using
+``--config`` option. Variables with specific names  will be picked up by the
+framework and used to modify the behaviour of Workload automation.
+
+---------------------
+
+.. _available_settings:
+
+.. include:: run_config/Run_Configuration.rst
+
+---------------------
+
+.. _meta-configuration:
+
+Meta Configuration
+------------------
+
+There are also a couple of settings are used to provide additional metadata
+for a run. These may get picked up by instruments or output processors to
+attach context to results.
+
+.. include:: run_config/Meta_Configuration.rst
+
+---------------------
+
+.. _envvars:
+
+Environment Variables
+---------------------
+
+In addition to standard configuration described above, WA behaviour can be
+altered through environment variables. These can determine where WA looks for
+various assets when it starts.
+
+.. confval:: WA_USER_DIRECTORY
+
+   This is the location WA will look for config.yaml, plugins,  dependencies,
+   and it will also be used for local caches, etc. If this variable is not set,
+   the default location is ``~/.workload_automation`` (this is created when WA
+   is installed).
+
+   .. note:: This location **must** be writable by the user who runs WA.
+
+
+.. confval:: WA_LOG_BUFFER_CAPACITY
+
+    Specifies the capacity (in log records) for the early log handler which is
+    used to buffer log records until a log file becomes available. If the is not
+    set, the default value of ``1000`` will be used. This should sufficient for
+    most scenarios, however this may need to be increased, e.g. if plugin loader
+    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_information/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.