junction-elements.rst: Add junctions walkthrough

This is part of the work towards #437.

2 files changed, 75 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 3557ac505..381ab90ad 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -118,8 +118,11 @@ html devhelp: templates sessions
 	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
 	    $(wildcard source/*.rst) \
 	    $(wildcard source/tutorial/*.rst) \
+            $(wildcard source/advanced-features/*.rst) \
 	    $(wildcard source/examples/*.rst) \
 	    $(wildcard source/elements/*.rst) \
 	    $(wildcard source/sources/*.rst)
 	@echo
 	@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"
+# Makefile for Sphinx documentation
+#
diff --git a/doc/source/advanced-features/junction-elements.rst b/doc/source/advanced-features/junction-elements.rst
new file mode 100644
index 000000000..4457077aa
--- /dev/null
+++ b/doc/source/advanced-features/junction-elements.rst
@@ -0,0 +1,72 @@
+
+
+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 project found in the BuildStream
+doc/examples/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
+
+This element consists of a script which calls hello.bst's hello command.
+
+Building callHello.bst,
+
+.. raw:: html
+   :file: ../sessions-stored/junctions-build.html
+
+You can see that the hello.bst element and it's 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-stored/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-stored/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.