doc: Refactoring junction documentation

Renamed the "Advanced topics" section to "Combining projects", and splitting
up the junctions section into two separate documents, one which describes
the simplest junction example and another which explains how to use
workspaces in conjunction with junctions.

This commit also makes some minor changes the examples, correcting
some grammatical errors, improving links and formatting, also rewording
a `note::` in order to clarify that it would be unusual to junction
a project that is in a subdirectory.

11 files changed, 177 insertions, 97 deletions

diff --git a/doc/Makefile b/doc/Makefile
index ba8934bde..a7150e6d7 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -143,7 +143,7 @@ html devhelp: templates sessions badges
 	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
 	    $(wildcard source/*.rst) \
 	    $(wildcard source/tutorial/*.rst) \
-            $(wildcard source/advanced-features/*.rst) \
+            $(wildcard source/junctions/*.rst) \
 	    $(wildcard source/examples/*.rst) \
 	    $(wildcard source/elements/*.rst) \
 	    $(wildcard source/sources/*.rst) \
diff --git a/doc/examples/first-project/project.conf b/doc/examples/first-project/project.conf
index 2e3d086b1..f66376146 100644
--- a/doc/examples/first-project/project.conf
+++ b/doc/examples/first-project/project.conf
@@ -2,7 +2,7 @@
 name: first-project
 
 # Required BuildStream format version
-format-version: 18
+format-version: 25
 
 # Subdirectory where elements are stored
 element-path: elements
diff --git a/doc/sessions/junctions.run b/doc/sessions/junctions.run
index fc9014203..b03b06a15 100644
--- a/doc/sessions/junctions.run
+++ b/doc/sessions/junctions.run
@@ -10,11 +10,19 @@ commands:
   output: ../source/sessions/junctions-shell.html
   command: shell callHello.bst -- /bin/sh callHello.sh
 
+# Open a workspace on the junction:
+- directory: ../examples/junctions
+  output: ../source/sessions/junctions-workspace-open-subproject.html
+  command: workspace open --directory workspace_subproject hello-junction.bst
+
 # Open a crossJunction workspace:
 - directory: ../examples/junctions
   output: ../source/sessions/junctions-workspace-open.html
   command: workspace open --directory workspace_hello hello-junction.bst:hello.bst
 
-# Remove the workspace 
+# Remove the workspaces
+- directory: ../examples/junctions
+  command: workspace close --remove-dir hello-junction.bst
+
 - directory: ../examples/junctions
   command: workspace close --remove-dir hello-junction.bst:hello.bst
diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst
deleted file mode 100644
index 6bdc962fb..000000000
--- a/doc/source/advanced-features/junction-elements.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-
-
-.. _advanced_junction:
-
-Junction elements
-=================
-BuildStream's junction elements are used to import other BuildStream
-projects. This allows you to depend on elements that are part of an
-upstream project.
-
-
-A simple example
-----------------
-
-.. note::
-
-    This example is distributed with BuildStream in the
-    `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_
-    subdirectory.
-
-Below is a simple example of bst file for a junction element:
-
-.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst
-    :language: yaml
-
-This element imports the autotools example subproject found in the
-BuildStream doc/examples/junctions/autotools subdirectory.
-
-.. note::
-
-    While for this example we're using a local source, another common use-case,
-    for junction elements is including a remote, version contolled project,
-    having a source type such as `-kind: git`.
-
-The below bst file describes an element which depends on the hello.bst element
-from the autotools example:
-
-.. literalinclude:: ../../examples/junctions/elements/callHello.bst
-    :language: yaml
-
-This element consists of a script which calls hello.bst's hello command.
-
-Building callHello.bst,
-
-.. raw:: html
-   :file: ../sessions/junctions-build.html
-
-You can see that the hello.bst element and its dependencies from the autotools
-project have been build as part of the pipeline for callHello.bst.
-
-We can now invoke `bst shell`
-
-.. raw:: html
-   :file: ../sessions/junctions-shell.html
-
-This runs the script files/callHello.sh which will makes use of the hello command from the hello.bst element in the autotools project.
-
-
-Cross-junction workspaces
--------------------------
-You can open workspaces for elements in the project refered to by the junction
-using the syntax `bst open ${junction-name}:{element-name}`. In this example,
-
-.. raw:: html
-   :file: ../sessions/junctions-workspace-open.html
-
-This has opened a workspace for the hello.bst element from the autotools project.
-This workspace can now be used as normal.
-
-
-Further reading
----------------
-For an example of junction elements being used in a real project, take a look
-at the `freedesktop-sdk junction
-<https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/master/elements/freedesktop-sdk.bst>`_
-in the `gnome-build-meta <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_ project.
diff --git a/doc/source/developing/workspaces.rst b/doc/source/developing/workspaces.rst
index e4ad66da8..2413c56ff 100644
--- a/doc/source/developing/workspaces.rst
+++ b/doc/source/developing/workspaces.rst
@@ -4,8 +4,8 @@
 
 Workspaces
 ==========
-In this section we will cover the use of BuildStream's workspaces feature when devloping on a 
-BuildStream project.
+In this section we will cover the use of BuildStream's workspaces feature when
+devloping a BuildStream project.
 
 .. note::
 
diff --git a/doc/source/junctions/junction-elements.rst b/doc/source/junctions/junction-elements.rst
new file mode 100644
index 000000000..8de3d5361
--- /dev/null
+++ b/doc/source/junctions/junction-elements.rst
@@ -0,0 +1,92 @@
+
+
+.. _junction_elements:
+
+Junction elements
+=================
+BuildStream's :mod:`junction <elements.junction>` elements are the mechanism which
+allow projects to interact and depend on eachother.
+
+Junction elements represent the BuildStream project you are depending, and behave
+much like other elements in the sense that they can be :ref:`fetched <invoking_source_fetch>`
+and :ref:`tracked <invoking_source_track>` like other elements, except that regular
+elements cannot *depend* on junctions directly, nor can junctions be :ref:`built <invoking_build>`.
+Instead, junctions act like a window into another project you depend on, and allow
+elements of your project to depend on elements exposed by the project referenced by
+the junction.
+
+Projects which are junctioned by your project are referred to as *subprojects*.
+
+
+A simple example
+----------------
+
+.. note::
+
+    This example is distributed with BuildStream in the
+    `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_
+    subdirectory.
+
+Below is a simple example of bst file for the junction element, which
+we have called ``hello-junction.bst`` in this project:
+
+.. literalinclude:: ../../examples/junctions/elements/hello-junction.bst
+    :language: yaml
+
+This element imports the autotools example subproject distributed with BuildStream
+in the `doc/examples/junctions/autotools <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions/autotools>`_
+subdirectory.
+
+.. note::
+
+    For the sake of this example we are using a local source in a subdirectory
+    of the example project.
+
+    Since junctions allow interoperability of projects, it would be more common
+    to use a junction to a remote project under separate revision control, possibly
+    using a ``kind: git`` source.
+
+The below bst file describes the element ``callHello.bst``, which depends on the
+``hello.bst`` element from the autotools example:
+
+.. literalinclude:: ../../examples/junctions/elements/callHello.bst
+    :language: yaml
+
+Note how this element refers to the previously declared ``hello-junction.bst``
+junction in its :ref:`dependency dictionary <format_dependencies>`. This dependency
+expresses that we are depending on the ``hello.bst`` element in the project
+which ``hello-junction.bst`` refers to.
+
+The ``callHello.bst`` element simply imports a ``callHello.sh`` shell script which
+calls the hello command provided by ``hello.bst``:
+
+.. literalinclude:: ../../examples/junctions/files/callHello.sh
+    :language: shell
+
+
+Building and running
+--------------------
+Building the ``callHello.bst`` element which requires an external project
+is just a matter of invoking :ref:`bst build <invoking_build>` in the
+regular way:
+
+.. raw:: html
+   :file: ../sessions/junctions-build.html
+
+You can see that the hello.bst element and its dependencies from the autotools
+project have been built as a part of the pipeline for callHello.bst.
+
+We can now invoke :ref:`bst shell <invoking_shell>` and run our ``callHello.sh``
+script, which in turn also calls the ``hello`` program installed by the
+subproject's ``hello.bst`` element.
+
+.. raw:: html
+   :file: ../sessions/junctions-shell.html
+
+
+Further reading
+---------------
+For an example of junction elements being used in a real project, take a look
+at the `freedesktop-sdk junction
+<https://gitlab.gnome.org/GNOME/gnome-build-meta/blob/master/elements/freedesktop-sdk.bst>`_
+in the `gnome-build-meta <https://gitlab.gnome.org/GNOME/gnome-build-meta>`_ project.
diff --git a/doc/source/junctions/junction-workspaces.rst b/doc/source/junctions/junction-workspaces.rst
new file mode 100644
index 000000000..a9176063c
--- /dev/null
+++ b/doc/source/junctions/junction-workspaces.rst
@@ -0,0 +1,51 @@
+
+
+.. _junction_workspaces:
+
+Workspaces and subprojects
+==========================
+When developping a project with :mod:`junctions <elements.junction>` and
+subprojects, you will probably end up needing to work on the subprojects
+as well.
+
+Opening :ref:`workspaces <developing_workspaces>` works mostly in the
+same way as it does with subprojects as it does for elements directly
+in your own project.
+
+.. note::
+
+    This section runs commands on the same example project presented in the
+    :ref:`previous section <junction_elements>`, which is distributed with BuildStream in the
+    `doc/examples/junctions <https://gitlab.com/BuildStream/buildstream/tree/master/doc/examples/junctions>`_
+    subdirectory.
+
+
+Workspacing a junction
+----------------------
+Sometimes you need to work on the elements declared in a subproject
+directly. As the downstream consumer of a junctioned project, it makes
+sense that you might need to work on that project as well in order
+to satisfy the needs of your downstream project.
+
+You can easily work on your subproject by :ref:`opening a workspace <invoking_workspace_open>`
+on the junction element directly.
+
+.. raw:: html
+   :file: ../sessions/junctions-workspace-open-subproject.html
+
+After opening a workspace on the junction element, the open workspace
+is used to define the subproject, allowing you to make changes to
+how the subproject is built, add new dependencies and configure the
+subproject in any way.
+
+
+Cross-junction workspaces
+-------------------------
+You can open workspaces for elements in the project refered to by the junction
+using the syntax ``bst open ${junction-name}:{element-name}``. In this example,
+
+.. raw:: html
+   :file: ../sessions/junctions-workspace-open.html
+
+This has opened a workspace for the hello.bst element from the autotools project.
+This workspace can now be used as normal.
diff --git a/doc/source/main_glossary.rst b/doc/source/main_glossary.rst
index a2bb58540..fb9506c7f 100644
--- a/doc/source/main_glossary.rst
+++ b/doc/source/main_glossary.rst
@@ -77,7 +77,7 @@ Glossary
        See :mod:`Junction reference <elements.junction>` for details on how to
        configure junction elements.
 
-       See :ref:`Junction guide <advanced_junction>` for details on how to use
+       See :ref:`Junction guide <junction_elements>` for details on how to use
        junction elements.
 
 
@@ -126,6 +126,11 @@ Glossary
        :term:`Element <Element>` configuration.
 
 
+   Subproject
+       Subprojects are :term:`projects <Project>` which are referred
+       to by a :term:`Junction`.
+
+
    Workspace
        Workspaces allow building one or more elements using a local, and
        potentially modified, copy of their sources.
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index 48553087c..067e7bb16 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -13,8 +13,8 @@ guides and information on user preferences and configuration.
 
    using_tutorial
    using_developing
-   using_advanced_features
-   using_examples
+   using_junctions
    using_config
    using_commands
    using_configuring_cache_server
+   using_examples
diff --git a/doc/source/using_advanced_features.rst b/doc/source/using_advanced_features.rst
deleted file mode 100644
index 585b3573c..000000000
--- a/doc/source/using_advanced_features.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-Advanced features
-=================
-This section provides some step by step walkthroughs which are meant to help the
-user quickly get more familiar with some of BuildStream's more advanced
-features.
-
-.. toctree::
-   :numbered:
-   :maxdepth: 1
-
-   advanced-features/junction-elements
diff --git a/doc/source/using_junctions.rst b/doc/source/using_junctions.rst
new file mode 100644
index 000000000..85f1638b1
--- /dev/null
+++ b/doc/source/using_junctions.rst
@@ -0,0 +1,13 @@
+
+
+Combining projects
+==================
+This section covers the features which allow BuildStream projects to
+depend on eachother.
+
+.. toctree::
+   :numbered:
+   :maxdepth: 1
+
+   junctions/junction-elements
+   junctions/junction-workspaces