Tristan/architecture docs

See merge request !907

We shouldn't need it to persist now that we cache failed build dirs.

This change breaks the test
`tests/integration/shell.py::test_sysroot_workspace_visible`.
I can no longer see a use-case for this test.
AIUI, it tested that the failed build sysroot stored in the builddir has
the workspace's files in, despite the workspace being unmounted.
I believe this behaviour is made redundant by cached buildtrees.

This fixes part of #539

This includes changes in app.py:
* Interactive failure shell no longer uses the failed build sysroot,
  defaulting to the cached build tree.

Changes in element.py are:
* Errors caused by building don't store the failed build sysroot,
  instead storing that a sandbox can be created to debug the error.
* When staging sources, will stage the element's cached build tree if it
  exists.

Changes in _exceptions.py:
* BstError.sandbox is now a flag of whether a sandbox can be opened up
  to debug the error.

Changes in widget.py:
* Don't try to print any information about the sandbox.

Changes in _message.py:
* Fix documentation so Message.sandbox is not a directory any more.

This is part of #539

This is related to #539

i.e. instead of taking a directory that must contain "root" and
"scratch", and treating "root" as the root, use the directory directly.

In element.py:
* __sandbox takes the `bare_sandbox` arg, to pass into the sandbox's constructor

In sandbox.py:
* If bare_sandbox, `_root` is the passed-in directory, and `__scratch`
  is None.
* Trying to use `__scratch` when bare_sandbox is True is a bug.

In _mount.py:
* Don't get the value of `__scratch` if it's not needed.

This is part of #539

This is related to #539

Jonathan/debug remote failed builds

See merge request !869

The addition of the pull-buildtrees flag will be used to override
the default behaviour of remote artifact cache pulling. Included
is the required changes to completions tests.

The addition of the pullbuildtrees option to the users global
buildstream.conf will be used to override the default behaviour
of remote artifact cache pulling.

The addition of cached buildtrees being included in element
artifacts has led to mostly redundant download overheads when
pulling from a remote artifact server. As such the default behaviour
of pull shouldn't fetch the buildtree object if available.

_stream.py: propagate if pullbuildtrees has been set via cli or
user config to the PullQueue.

pullqueue.py: add extensible attributes to determine required/
excluded directories for element pull jobs.

element.py: extend relevant pull logic for specified subdir
consideration and ensure push logic does not lead to partial
artifact pushes. Change assumption that buildtree can be
extracted if artifact is cached.

_artifactcache/: artifactcache.py & cascache.py inclusion of
helper functions for subdir artifact checking & fetching, fetch
logic extended to only pull required artifact directories.
extract & checkout updated to handle full/partial operation.

tests/: addition of integration test pullbuildtrees.py,
buildtrees.py adapted cli options, testutils/artifactshare.py
has_artifact changed to return artifact digest on true condition.