As discussed over the mailing list, reformat code using Black. This is a
one-off change to reformat all our codebase. Moving forward, we
shouldn't expect such blanket reformats. Rather, we expect each change
to already comply with the Black formatting style.

We currently have two sites file containing redundant information.

- tests/testutils/site.py: Remove IS_{LINUX,WSL,WINDOWS}
- rest: Change imports to import those from
buildstream/tests/_utils/site.py

- Rename plugintestutils to testing.

- Don't run the tests from bst-plugins-template. This imports
  buildstream.plugintestutils so will have to be disabled to get
  through CI. This can be re nabled once bst-plugins-template has been
  patched.

Replace some popular copypasta.

This important-looking invocation:

    os.path.join(datafiles.dirname, datafiles.basename)

is equivalent to this shorter invocation:

    project = str(datafiles)

It seems like it's very popular copypasta, replace it with the shorter
one thus:

    # Use 'gsed' or 'sed' etc. as appropriate for your system.
    git config --global alias.sub '!f() { git grep --name-only --null "$1" | gxargs --null gsed --in-place --expression "s/$1/$2/g" ; }; f'
    git sub 'os.path.join(datafiles.dirname, datafiles.basename)' 'str(datafiles)'

Pylint can't know that pytest's fixtures are used in a file and
therefore reports false positives. Silencing all those errors

Pylint doesn't play well with pytest fixtures, we therefore need to
silence this error.

For parameters that are required as part of an API, prefix them
by "_" to make it clear they are unused

We want external plugins to be able to make use of the core testing utils.
This commit exposes the basic utilities which are currently in use in
bst-external plugins. If necessary, more utilities could be exposed in the
future.

Moves the following files from tests/testutils/ to
buildstream/plugintestingutils/:
o runcli.py
o integration.py

As part of this, this commit makes the following changes to runcli.py
and integration.py:
o runcli.py: Fix linting errors
o runcli.py: Add user facing documentation
o Integration.py: Add user facing documentation

This commit marks 'bst checkout' as a 'hidden' command. If used,
the user will be prompted to use the new 'bst artifact checkout'
command.

All tests which used 'bst checkout' have been modified to use
the new artifact sub-command.

This partially solves #822.

  o doc/Makefile: Added new directory to collect rst files from

  o doc/examples/first-project: Added the "first-project" example
    project.

  o doc/source/sessions/first-project-*.html: Added the generated
    snippets

  o doc/source/using_tutorial.rst: Added the new main tutorial page

  o doc/source/tutorial/first-project.rst: Added part 1 of the tutorial here

  o tests/examples/first-project.py: Added test for the example project

This is largely based on an example by Javier Jardón, which was
submitted at https://gitlab.com/BuildStream/buildstream/merge_requests/323

Fixes #103