Instead of duplicating the whole test body, run it twice while
checking for a warning or an error depending on the parameter.

This also ensures it is exposed via the main buildstream __init__.py
file, fixes the imports of CoreWarnings, and adjusts the documentation
links to point to the right place.

Now the commands have documentation linkability so we can link to
them when referring to them anywhere in the docs. This reference
was previously referring to a bogus non-existent `build-stream track`,
maybe this dates way back to the days before we named the frontend `bst`.

Fixes the configurable warning part of this to properly link
to the project.conf documentation describing what configurable
warnings actually are.

Also fix the plugin raise the actual configurable warning which
it advertizes that it raises; which is 'inconsistent-submodule',
not 'inconsistent-submodules'.

Change 'INCONSISTENT_SUBMODULE' for 'WARN_INCONSISTENT_SUBMODULE' to
make things a bit more readable and comprehensive.

Misc cleanups

See merge request !993

This is guaranteed to be called only once for a given session once the
sources are known to be Consistency.CACHED, if source tracking is enabled
in the session for this source, then this will only be called if the
sources become cached after tracking completes.

 o Unlisted submodule warning

   Now the git plugin will issue a configurable warning if a submodule
   exists and is used (checking out the submodule is not disabled),
   but is not specified in the source configuration.

 o Invalid submodule warning

   Now the git source plugin will issue a warning if the configuration
   specified a submodule which does not exist in the underlying git repository.

As a side effect, this patch also changes the flow control of the git
plugin such that submodules which are explicitly set to not be
checked out, are also not fetched but instead ignored completely.

Now that we have Source.validate_cache(), this is a better place to emmit
the ref-not-in-track warning, since it will be emmitted at the earliest
opportunity and not only at Source.stage() or Source.init_workspace().

This also allows us to remove the `self.tracked` local state, and cleanup
some convoluted calling paths, removing some unnecessary parameters from
the usual codepaths and making the plugin overall more readable.

A function for removing paths from a git repo, can also
be used to remove submodules.

 o Test that it is not triggered in show before fetch, because we
   don't know about the unlisted submodules yet

 o Test that it is triggered by a fetch command

 o Test that it is triggered by `show` after having completed a
   fetch command, since now we have the repository and know about
   the unlisted submodule

 o Test all of this under warning or error conditions (parameterized
   for fatal-warnings)

   o Test that it is not triggered in show before fetch, because we
     don't know the submodules yet so we cannot know if they are
     valid or not.

   o Test that it is triggered by a fetch command

   o Test that it is triggered by `show` after having completed a
     fetch command, since now we have the repository and know which
     specified submodules are invalid

   o Test all of this under warning or error conditions (parameterized
     for fatal-warnings)

Implement submodule warnings

See merge request !996

i.e. with a given directory and filename, check parent directories until
either a directory with the filename is found, or you reach the root of
the filesystem.

This is a part of #222

WorkspaceProject contains all the information needed to refer back to a
project from its workspace (currently this is the project path and the
element used to create this workspace)

This is stored within a WorkspaceProjectCache object, which keeps
WorkspaceProjects around so they don't need to be loaded from disk
repeatedly.

Workspaces has been extended to contain the WorkspaceProjectCache, and
will use it when opening and closing workspaces.

Context has been extended to contain a WorkspaceProjectCache, as there
are times when we want to use it before a Workspaces can be initialised
(looking up a WorkspaceProject to find the directory that the project is
in)

This is a part of #222

This is a part of #222

This is a part of #222

Searching for the workspace file is preferred to searching for the
project file for the moment, because it avoids the circumstance of
the workspaces being inside a directory where a higher-level
ctory
may have project.conf (but may not be a buildstream project).

This is a part of #222

This is a part of #222

This is a part of #222

This is a part of #222

cli: Interactively warn if the user is trying to close the workspace they're using to load the project

This involves changes in:
* _stream.py:
  * Add the helper Stream.workspace_is_required()
* userconfig.yaml:
  * Add a default value for prompt.really-workspace-close-project-inaccessible
* _context.py:
  * Load the prompt 'really-workspace-close-project-inaccessible' from
    user config.
* cli.py:
  * If buildstream is invoked interactively, prompt the user to confirm
    that they want to close the workspace they're using to load this
    project.

This is a part of #222

This is a part of #222

This is a part of #222