Making changes to various documents:

format.rst
index.rst
install.rst
modifyingandtesting.rst
pluginindex.rst

7 files changed, 261 insertions, 16 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 8949cba92..6edb2947e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,4 +1,4 @@
-image: buildstream/buildstream-fedora:master-42-571406d
+image: buildstream/buildstream-fedora:master-54-16ff337
 
 cache:
   key: "$CI_JOB_NAME-"
diff --git a/doc/source/format.rst b/doc/source/format.rst
index 80bc71b95..5ca1a06e1 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -56,6 +56,8 @@ details here in order to have a more complete initial example.
 Let's break down the above and give a brief explanation of what these attributes mean.
 
 
+.. _format_kind:
+
 Kind
 ~~~~
 
@@ -75,6 +77,8 @@ To refer to a third party plugin, prefix the plugin with its package, for exampl
    kind: buildstream-plugins:dpkg_build
 
 
+.. _format_depends:
+
 Depends
 ~~~~~~~
 
@@ -136,7 +140,6 @@ Asides from the common ``kind`` and ``directory`` attributes which may be applie
 Sources, refer to the Source specific documentation for meaningful attributes for the
 particular Source.
 
-
 Variables
 ~~~~~~~~~
 
@@ -152,6 +155,8 @@ declared and overridden in the :ref:`projectconf`
 See `Using Variables`_ below for a more in depth discussion on variables in BuildStream.
 
 
+.. _format_environment:
+
 Environment
 ~~~~~~~~~~~
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 36aa749bc..69974a3ac 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -21,6 +21,9 @@ These pipelines are composed of abstract elements which perform mutations on
 on *filesystem data* as input and output, and are related to eachother by their
 dependencies.
 
+Quick Start
+-----------
+* :ref:`modifyingandtesting`
 
 Installing
 ----------
diff --git a/doc/source/install.rst b/doc/source/install.rst
index c9086b9d7..37023b0fd 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -12,6 +12,12 @@ using python's ``pip`` package manager.
 This page has some instructions for installing the dependencies you
 will need using your distribution's package manager, this is followed by
 instructions for installing BuildStream itself :ref:`using pip <installing_pip>`.
+=======
+BuildStream on your host
+========================
+
+Until BuildStream is available in your distro, there are a few hoops to jump
+through to get started.
 
 If your system cannot provide the base system requirements for BuildStream,
 then we have some instructions which can help you get started
@@ -20,15 +26,18 @@ then we have some instructions which can help you get started
 
 System requirements
 -------------------
+
 BuildStream requires the following base system requirements:
 
 * python3 >= 3.4
 * ruamel.yaml python library
-* PyGObject introspection bindings
 * OSTree >= v2017.8 with introspection data
+* bubblewrap
+* gobject-introspection
+* PyGObject introspection bindings
 
 Note that ``ruamel.yaml`` is a pure python library which is normally
-obtainable via pip, however there seems to be some problems with installing
+obtainable via pip, however, there seem to be some problems with installing
 this package so we recommend installing it with your package manager first.
 
 For the purpose of installing BuildStream while there are no distro packages,
@@ -36,20 +45,22 @@ you will additionally need:
 
 * pip for python3 (only required for setup)
 * Python 3 development libraries and headers
-* git (to checkout buildstream)
+* git (to checkout or install BuildStream from git)
 
 Here are some examples of how to prepare the base requirements on
 some distros.
 
 Arch
 ~~~~
-Install the dependencies with:
+
+Install the dependencies with::
 
   sudo pacman -S fuse2 python python-pip python-gobject git \
                  ostree bubblewrap python-ruamel-yaml
 
 Debian Stretch
 ~~~~~~~~~~~~~~
+
 With stretch, you first need to ensure that you have the backports repository
 setup as described `here <https://backports.debian.org/Instructions/>`_
 
@@ -61,7 +72,7 @@ And then running::
 
   sudo apt-get update
 
-At this point you should be able to get the system requirements with::
+At this point, you should be able to get the system requirements with::
 
   sudo apt-get install \
       python3-dev python3-pip git python3-gi \
@@ -69,11 +80,11 @@ At this point you should be able to get the system requirements with::
   sudo apt-get install -t stretch-backports \
       gir1.2-ostree-1.0 ostree
 
-
 Debian Buster or Sid
 ~~~~~~~~~~~~~~~~~~~~
-For debian unstable or testing, only the following line should be enough
-to get the base system requirements installed::
+
+For Debian unstable or testing, the following line should be enough
+to get most of the base system requirements installed::
 
   sudo apt-get install \
       python3-dev python3-pip git \
@@ -83,7 +94,8 @@ to get the base system requirements installed::
 
 Fedora
 ~~~~~~
-For recent fedora systems, the following line should get you the system
+
+For recent Fedora systems, the following line should get you the system
 requirements you need::
 
   dnf install -y bubblewrap fuse fuse-libs git python3-gobject \
@@ -94,16 +106,27 @@ requirements you need::
 
 Installing with pip
 -------------------
+
+User installation with pip
+--------------------------
 Once you have the base system dependencies, you can clone the BuildStream
 git repository and install it as a regular user::
 
   git clone https://gitlab.com/BuildStream/buildstream.git
+
   cd buildstream
+
   pip3 install --user -e .
 
 This will install buildstream's pure python dependencies into
 your user's homedir in ``~/.local`` and will run BuildStream directly
 from the git checkout directory.
+=======
+
+  pip3 install --user .
+
+This will install BuildStream and its pure python dependencies directly into
+your user's home dir in ``~/.local``
 
 Keep following the instructions below to ensure that the ``bst``
 command is in your ``PATH`` and to enable bash completions for it.
@@ -119,27 +142,29 @@ command is in your ``PATH`` and to enable bash completions for it.
 
 Adjust PATH
 ~~~~~~~~~~~
+
 Since BuildStream is now installed under your local user's install directories,
 you need to ensure that ``PATH`` is adjusted.
 
-A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
+The regular way to do this is to add the following line to the end of your ``~/.bashrc``::
 
   export PATH=${PATH}:~/.local/bin
 
 
 Bash Completions
 ~~~~~~~~~~~~~~~~
+
 Bash completions are supported by sourcing the ``buildstream/data/bst``
 script found in the BuildStream repository. On many systems this script
 can be installed into a completions directory but when installing BuildStream
-without a package manager this is not an option.
+without a package manager, this is not an option.
 
 To enable completions for an installation of BuildStream you
 installed yourself from git, just append the script verbatim
 to your ``~/.bash_completion``:
 
 .. literalinclude:: ../../buildstream/data/bst
-   :language: yaml
+  :language: yaml
 
 
 Upgrading BuildStream with pip
@@ -156,5 +181,18 @@ need to cleanly reinstall BuildStream::
 
   pip3 uninstall buildstream
   cd /path/to/buildstream
+
+
+Upgrading with pip
+~~~~~~~~~~~~~~~~~~
+
+To upgrade a previously installed BuildStream, you will need to pull
+the latest changes and reinstall as such::
+
+  pip3 uninstall buildstream
+
+  cd buildstream
+
   git pull --rebase
+
   pip3 install --user .
diff --git a/doc/source/invoking.rst b/doc/source/invoking.rst
index 1c995a1e7..5bfe50d3d 100644
--- a/doc/source/invoking.rst
+++ b/doc/source/invoking.rst
@@ -5,6 +5,88 @@
 Invoking BuildStream
 ====================
 
-.. click:: buildstream._frontend.main:cli
+.. click:: buildstream._frontend.cli:cli
    :prog: bst
-   :show-nested:
+
+----
+
+.. _invoking_build:
+.. click:: buildstream._frontend.cli:build
+   :prog: build
+
+----
+
+.. click:: buildstream._frontend.cli:fetch
+   :prog: fetch
+
+----
+
+.. _invoking_track:
+
+.. click:: buildstream._frontend.cli:track
+   :prog: track
+
+----
+
+.. click:: buildstream._frontend.cli:pull
+   :prog: pull
+
+----
+
+.. click:: buildstream._frontend.cli:push
+   :prog: push
+
+----
+
+.. click:: buildstream._frontend.cli:show
+   :prog: show
+
+----
+
+.. _invoking_shell:
+
+.. click:: buildstream._frontend.cli:shell
+   :prog: shell
+
+----
+
+.. _invoking_checkout:
+
+.. click:: buildstream._frontend.cli:checkout
+   :prog: checkout
+
+----
+
+.. click:: buildstream._frontend.cli:source_bundle
+   :prog: source bundle
+
+----
+
+.. _invoking_workspace:
+
+.. click:: buildstream._frontend.cli:workspace
+   :prog: workspace
+
+----
+
+.. _invoking_workspace_open:
+
+.. click:: buildstream._frontend.cli:workspace_open
+   :prog: workspace open
+
+----
+
+.. _invoking_workspace_close:
+
+.. click:: buildstream._frontend.cli:workspace_close
+   :prog: workspace close
+
+----
+
+.. click:: buildstream._frontend.cli:workspace_reset
+   :prog: workspace reset
+
+----
+
+.. click:: buildstream._frontend.cli:workspace_list
+   :prog: workspace list
diff --git a/doc/source/main_authoring.rst b/doc/source/main_authoring.rst
index 5482e902e..f52c2892d 100644
--- a/doc/source/main_authoring.rst
+++ b/doc/source/main_authoring.rst
@@ -58,6 +58,8 @@ General Elements
 * :mod:`junction <elements.junction>` - Integrate subprojects
 
 
+.. _plugins_build:
+
 Build Elements
 ''''''''''''''
 
diff --git a/doc/source/modifyingandtesting.rst b/doc/source/modifyingandtesting.rst
new file mode 100644
index 000000000..be5fb29c2
--- /dev/null
+++ b/doc/source/modifyingandtesting.rst
@@ -0,0 +1,115 @@
+:orphan:
+
+.. _modifyingandtesting:
+
+Modifying and testing code
+==========================
+
+Creating a workspace
+--------------------
+
+A workspace is a directory containing a copy of a given project element's source code and is usually used when you want to modify and test your code, without changing the original.
+
+Workspaces allow you to reduce the time taken to edit/compile/test your work by allowing you to build and test changes without needing to adjust the specific project elements directly or having to publish intermediate commits of your temporary work.
+
+The following example assumes you have a project that can be built (Has the appropriate .bst files in place)
+
+.. note::
+
+  The project does not need to build sucessfully, only have the ability to build
+
+.. If not, go to :ref:`buildproject`
+
+In this example we be using `gedit.bst`, but this will work on any buildable project
+
+----
+
+To start off, we will be using the :ref:`invoking_workspace` command in order to create a copy of your project files in a declared directory
+
+From the root of the project directory run:
+
+.. code:: bash
+
+ mkdir ~/WORKSPACES
+ bst workspace open core/gedit.bst ~/WORKSPACES/gedit
+
+This will create a new directory called "workspace1" in the current directory
+
+.. code:: bash
+
+ ls
+
+ elements  files  keys  project.conf  workspace1
+
+Modifying code in the workspace
+-------------------------------
+
+To modify the workspace copy of your project more easily, we will now move to the workspace directory
+
+.. code:: bash
+
+ cd workspace1
+
+In here you will see the the contents of the source repository.
+
+This is the same source that would normally be used to build the selected element.
+
+.. code:: bash
+
+ ls
+
+ AUTHORS  autogen.sh  ChangeLog  configure.ac  CONTRIBUTING.md
+ COPYING  data  docs  gedit  gedit.doap  git.mk  HACKING  help
+ libgd  m4  MAINTAINERS  Makefile.am  NEWS  osx  plugins  po
+ README  tools  win32
+
+
+.. note::
+
+ For sources which originate from a git repository, the workspace will be in 'detached HEAD' state and point to the exact revision which would normally be built. You can checkout the master branch and pull or push changes to the upstream directly from an open workspace.
+
+
+Using the text editing tool of your choice, you can now open these files and make any modifications that you wish to the elements source code.
+
+
+Rebuilding the project using open workspaces
+--------------------------------------------
+
+Return to the root of your original project and then rebuild the project as normal using:
+
+.. code:: bash
+
+ bst build core/gedit.bst
+
+Instead of building gedit from the originally defined sources, BuildStream will use the sources directly from the open workspace.
+This will happen for all elements that have a workspace attached to them.
+
+Verifying changes
+-----------------
+
+You can use the :ref:`invoking_shell` command to launch a sandboxed shell environment where the built gedit artifact and it's runtime dependencies are staged. 
+
+.. code:: bash
+
+ bst shell core/gedit
+
+You can now launch the gedit application you have built and inspect the behavior. You can also debug it with any tools found in the sandboxed runtime environment, such as gdb or valgrind.
+
+Closing a workspace
+-------------------
+
+Once you are finished with the workspace, you can use the :ref:`invoking_workspace_close` command to detach the workspace from the element.
+
+This is done by returning to the project directory and running:
+
+.. code:: bash
+
+ bst workspace close core/gedit.bst
+
+This will remove the references to the workspace from the element and allow it to use the original sources.
+
+.. note::
+
+ The directory and its contents will not be removed.
+
+ The `--remove-dir` flag can be used alongside the previous command in order to remove the closed workspace.