From e4d163ab0b82d1b9fe17d55a5ef93a98e9d6738c Mon Sep 17 00:00:00 2001
From: Chandan Singh <csingh43@bloomberg.net>
Date: Tue, 12 Feb 2019 19:57:09 +0530
Subject: Document how to refer to cross-junction dependencies inline

In the previous commit, we added support to express cross-junction
dependencies inline as simple strings. Document it along with the
version in which the feature was added.
---
 buildstream/plugins/elements/junction.py |  2 ++
 doc/source/format_declaring.rst          | 35 ++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/buildstream/plugins/elements/junction.py b/buildstream/plugins/elements/junction.py
index ee5ed24d5..d2c62fe48 100644
--- a/buildstream/plugins/elements/junction.py
+++ b/buildstream/plugins/elements/junction.py
@@ -109,6 +109,8 @@ Junctions can configure options of the linked project. Options are never
 implicitly inherited across junctions, however, variables can be used to
 explicitly assign the same value to a subproject option.
 
+.. _core_junction_nested:
+
 Nested Junctions
 ----------------
 Junctions can be nested. That is, subprojects are allowed to have junctions on
diff --git a/doc/source/format_declaring.rst b/doc/source/format_declaring.rst
index b86bbfb1c..f69d4a479 100644
--- a/doc/source/format_declaring.rst
+++ b/doc/source/format_declaring.rst
@@ -381,6 +381,41 @@ Attributes:
      The ``junction`` attribute is available since :ref:`format version 1 <project_format_version>`
 
 
+Cross-junction dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As mentioned above, cross-junction dependencies can be specified using the
+``junction`` attribute. They can also be expressed as simple strings as a
+convenience shorthand. You can refer to cross-junction elements using the
+syntax ``{junction-name}:{element-name}``.
+
+For example, the following is logically same as the example above:
+
+.. code:: yaml
+
+   build-depends:
+     - baseproject.bst:foo.bst
+
+Similarly, you can also refer to cross-junction elements via the ``filename``
+attribute, like so:
+
+.. code:: yaml
+
+   depends:
+     - filename: baseproject.bst:foo.bst
+       type: build
+
+.. note::
+
+   BuildStream does not allow recursice lookups for junction elements. If a
+   filename contains more than one ``:`` (colon) character, an error will be
+   raised. See :ref:`nested junctions <core_junction_nested>` for more details
+   on nested junctions.
+
+.. note::
+
+   This shorthand is available since :ref:`format version 15 <project_format_version>`
+
+
 .. _format_dependencies_types:
 
 Dependency types
-- 
cgit v1.2.1