Documentation: Added user facing configuration section

Instead of documenting this in the Context object, provide a section
more targetted at users. The default configuration is shown in the
user facing documentation and removed from the Context object documentation
which is more targetted at API references for plugin authors.

2 files changed, 31 insertions, 0 deletions

diff --git a/doc/source/config.rst b/doc/source/config.rst
new file mode 100644
index 000000000..4dccafcaf
--- /dev/null
+++ b/doc/source/config.rst
@@ -0,0 +1,30 @@
+.. _config:
+
+
+User Configuration
+==================
+User configuration and preferences can be specified in a user provided
+configuration file, and usually also on the command line.
+
+Values specified in a user provided configuration file override the
+defaults, while command line options take precedence over any other
+specified configurations.
+
+
+Configuration file
+------------------
+Users can provide a configuration file to override parameters in
+the default configuration.
+
+Unless a configuration file is explicitly specified on the command line when
+invoking ``bst``, an attempt is made to load user specific configuration from
+``$XDG_CONFIG_HOME/buildstream.conf``. On most Linux based systems, the location
+will be ``~/.config/buildstream.conf``
+
+
+Default Configuration
+---------------------
+The default BuildStream configuration is specified here for reference:
+
+  .. literalinclude:: ../../buildstream/data/userconfig.yaml
+     :language: yaml
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fe6bf693c..c7a8b574e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -30,6 +30,7 @@ Here are some resources to help understand the BuildStream format and also to ge
 off the ground installing it on a new host.
 
 * :ref:`installing`
+* :ref:`config`
 * :ref:`format`