Document how to refer to cross-junction dependencies inlinechandan/junction-dependency-format

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.

2 files changed, 37 insertions, 0 deletions

diff --git a/buildstream/plugins/elements/junction.py b/buildstream/plugins/elements/junction.py
index 2550e1f79..ec7832bc6 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 714e1fa33..6a59557d4 100644
--- a/doc/source/format_declaring.rst
+++ b/doc/source/format_declaring.rst
@@ -401,6 +401,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 23 <project_format_version>`
+
+
 .. _format_dependencies_types:
 
 Dependency types