Reworked docs to be more open and clear

5 files changed, 47 insertions, 48 deletions

diff --git a/doc/source/buildproject.rst b/doc/source/buildproject.rst
index d9404e545..392b3578f 100644
--- a/doc/source/buildproject.rst
+++ b/doc/source/buildproject.rst
@@ -40,22 +40,20 @@ In this case, we will be using `gedit.bst` in elements/core
 
 from the root of the project repo run:
 
-    ``bst`` :ref:`invoking_build` ``core/gedit.bst``
+    ``bst`` :ref:`invoking_build` ``[project bst file]``
 
-To build the project.
+In this case, that would be core/gedit.bst
 
-If you get an error requesting the use of ``bst track``
+This will try to build the project.
 
-run:
-    ``bst`` :ref:`invoking_track` ``--deps all core/gedit.bst``
+----
 
-This will update all dependencies and should allow the build to pass.
+If you get an error requesting the use of ``bst track``
 
-Run the build command again and this time it should pass.
+run:
+    ``bst`` :ref:`invoking_track` ``--deps all [project bst file]``
 
-Once this is done, you can run:
-    ``bst`` :ref:`invoking_shell` ``core/gedit.bst``
+This command updates all project dependencies.
 
-Which will create a shell where gedit has been built.
-once the shell has been started, running the `gedit` command should begin the application
+Run the build command again and this time it should succeed.
 
diff --git a/doc/source/createproject.rst b/doc/source/createproject.rst
index 879e23767..52cefb716 100644
--- a/doc/source/createproject.rst
+++ b/doc/source/createproject.rst
@@ -46,7 +46,8 @@ Source files
 There are multiple ways of including source files with build stream, and this is done though things called plugins.
 
 The list of options can be found here :ref:`plugins_sources`
-And each option can be clicked for an example of "element"
+
+Each option can be clicked for an example of an "element"
 
 
 If you plan on following along with this tutorial, do the following:
@@ -81,22 +82,22 @@ Project.conf
 
 In the root of the project directory create a file called project.conf containing::
 
-  name: ProjectName  # The name you want to give to your project
-  element-path: elementsPath # The relative path to the "elements" directory
-  # The elements directory is where your .bst files will be stored 
-  aliases:
-    name:url # This is used so you can moderate the URLs/Repos used by your build. 
-             # This way, they can be modified in a single place instead of multiple
-             # Use this name in place of the url anywhere you would use it  
-    gnomesdk: https://sdk.gnome.org/    
-    
-  options:
-     arch:
-       type: arch
-       description: The machine architecture
-       values:
-       - x86_64
-       - i386
+    name: ProjectName  # The name you want to give to your project
+    element-path: elements # The relative path to the "elements" directory
+    # The elements directory is where your .bst files will be stored
+    aliases:
+      name: url # This is used so you can moderate the URLs/Repos used by your build.
+                # This way, they can be modified in a single place instead of multiple
+                # Use this name in place of the url anywhere you would use it
+      gnomesdk: https://sdk.gnome.org/
+
+    options:
+       arch:
+         type: arch
+         description: The machine architecture
+         values:
+         - x86_64
+         - i386
 
 
 step7.bst
@@ -104,7 +105,7 @@ step7.bst
 
 In the elements directory Create a file called step7.bst containing::
 
-  kind: cmake #This is an element plugin (linked below)
+  kind: cmake # This is a build element plugin (linked below)
   description: Cmake test
   
   depends:
@@ -114,10 +115,10 @@ In the elements directory Create a file called step7.bst containing::
       type: build
   
   sources:
-    - kind: tar #This is a Source Plugin
-      url: file:/src/step7.tar.gz
+    - kind: tar # This is a Source Plugin
+      url: [PathToProjectDir]/src/step7.tar.gz
   
-:ref:`plugins_elements:`
+:ref:`kind (plugins)<plugins_build>`
 
 :ref:`format_depends`
 
@@ -163,13 +164,3 @@ In the elements/dependencies directory Create a file called base-platform.bst co
       - ldconfig
 
 :ref:`format_public` 
-
-Building
-----
-
-From the project root directory run:
-
-  ``bst`` :ref:`invoking_build` ``step7.bst``
-  
-You can substitute step7.bst for your own .bst file
-
diff --git a/doc/source/invoking.rst b/doc/source/invoking.rst
index d774cf6b3..f4e479187 100644
--- a/doc/source/invoking.rst
+++ b/doc/source/invoking.rst
@@ -60,6 +60,8 @@ Invoking BuildStream
 
 ----
 
+.. _invoking_workspace:
+
 .. click:: buildstream._frontend.main:workspace
    :prog: workspace
 
diff --git a/doc/source/modifyingandtesting.rst b/doc/source/modifyingandtesting.rst
index 69551017a..3742bddcc 100644
--- a/doc/source/modifyingandtesting.rst
+++ b/doc/source/modifyingandtesting.rst
@@ -8,15 +8,23 @@ Creating a workspace
 
 A work space is a seperate directory containing a copy of the project sourcecode
 
-In this example, we will again be using gedit.bst, but this will work on any buildable project
+This example assumes you have a project that can be successfully built.
+
+If not, go to :ref:`buildproject`
+
+In this example we be using `gedit.bst`, but this will work on any buildable project
 
 ----
 
 From the root of the project directory run:
 
-    ``bst workspace open core/gedit.bst ../workspace1``
+    ``bst`` :ref:`invoking_workspace` ``open [project bst file] workspace1``
+
+In this case, that would be core/gedit.bst
+
+This will create a copy of your project files in the declared directory
 
-You now have an external copy of your project to work with.
+And give you an external copy of your project to work with.
 
 
 Modifying code in the workspace
@@ -24,7 +32,7 @@ Modifying code in the workspace
 
 To modify the workspace copy of your project, you will have to move to the workspace directory
 
-    ``cd ../workspace1``
+    ``cd workspace1``
 
 Here you will see the output of your build.
 
@@ -54,7 +62,7 @@ You can now use the shell command from the project root to run your project agai
 
 E.G:
 
-    ``bst shell core/gedit``
+    ``bst`` :ref:`invoking_shell` ``core/gedit``
 
 You should now see any changes that you made.
 
diff --git a/doc/source/pluginindex.rst b/doc/source/pluginindex.rst
index 2a74a11e5..5e41bf65e 100644
--- a/doc/source/pluginindex.rst
+++ b/doc/source/pluginindex.rst
@@ -19,7 +19,7 @@ General Elements
 * :mod:`compose <elements.compose>` - Compose the output of multiple elements
 * :mod:`script <elements.script>` - Run scripts to create output
 
-.. _plugins_elements:
+.. _plugins_build:
 
 Build Elements
 ~~~~~~~~~~~~~~