Extended the Documentation to cover out of source builds

buildstream/buildelement.py

@@ -23,6 +23,38 @@ BuildElement - Abstract class for build elements
 The BuildElement class is a convenience element one can derive from for
 implementing the most common case of element.
 
+Built-in functionality
+----------------------
+
+The BuildElement base class provides built in functionality that could be overridden by the
+individual plugins.
+
+This section will give a brief summary of how some of the common features work, some of them or the variables they
+use will be further detailed in the following sections.
+
+* Location for running commands
+
+ The ``command-subdir`` variable sets where the build commands will be executed, if the directory dose not exist it
+ will be created, it is defined relative to the buildroot.
+
+* Location for configuring the project
+
+ The ``conf-root`` is defined by default as ``.`` and is the location that specific build element can use to look
+ for build configuration files, currently autotools and cmake use this.
+
+ The configuration commands are run in ``command-subdir`` and by default ``conf-root`` is ``.`` so if
+ ``conf-root`` is not set the configuration files in ``command-subdir`` will be used.
+
+ By setting ``conf-root`` to ``"%{build-root}/Source/conf_location"`` and your source elements ``directory`` variable
+ to ``Source`` then the configuration files in the directory ``conf_location`` with in your Source will be used.
+ However the location where your configuration command will be run will still be wherever you set your
+ ``command-subdir`` to be.
+
+* Install Location
+
+  You should not change the ``install-root`` variable as it is a special writeable location in the sandbox but it is
+  useful when writing custom install instructions as it may need to be supplied as the ``DESTDIR``, please see the
+  cmake build element for example.
 
 Abstract method implementations
 -------------------------------

buildstream/source.py

@@ -20,6 +20,19 @@
 Source - Base source class
 ==========================
 
+Built-in functionality
+----------------------
+
+The Source base class provides built in functionality that could be overridden by the
+individual plugins.
+
+* Directory
+
+  The ``directory`` variable can be set for all sources of a type in project.conf
+  or per source within a element.
+
+  This sets the location with in the build root that the content of the source will be
+  loaded in to. If the location dose not exist it will be created.
 
 .. _core_source_abstract_methods: