[buildstream] 06/30: Add documentation for include directive.

[gi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

github-bot pushed a commit to branch valentindavid/flatpak-demo
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit d50ebc6b23a6df8b8759fe5510d15dd3379d01ee
Author: Valentin David <va...@codethink.co.uk>
AuthorDate: Wed Jun 13 13:44:06 2018 +0200

    Add documentation for include directive.
    
    Documents #331.
---
 doc/source/format_intro.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/source/format_intro.rst b/doc/source/format_intro.rst
index b1780f9..d0a934a 100644
--- a/doc/source/format_intro.rst
+++ b/doc/source/format_intro.rst
@@ -289,3 +289,36 @@ free form and not validated.
        # This element's `make install` is broken, replace it.
        (=):
        - cp src/program %{bindir}
+
+(@) Include
+~~~~~~~~~~~
+Indicates that content should be loaded from files.
+
+The include directive expects a list of strings. Those are file names
+relative to project directory. Or they can be prefixed with a junction
+name and a colon (':'). In that case, the remain of the string is a
+file name relative to the project of the junction.
+
+The include directive can be used in ``project.conf`` or in a ``.bst``
+file.  It can also be used in a file included by another include
+directive.
+
+Included files are composed into the including file. The files should
+take care of composition using list directives.
+
+Some ``project.conf`` configuration is not overridable by includes:
+``name``, ``format-version`` and ``element-path``.
+
+Junction elements never use values from included files from
+``project.conf``.  Variables, element overrides and source overrides
+required by junctions should all be directly in the ``project.conf``.
+
+Junction elements cannot use the include directive.
+
+**Example:**
+
+.. code:: yaml
+
+   elements:
+     (@):
+       - junction.bst:includes/element-overrides.bst