format_project.rst: Add documentation for default targets

doc/source/format_project.rst

@@ -945,6 +945,38 @@ Host side environment variable expansion is also supported:
      - '${XDG_RUNTIME_DIR}/pulse/native'
 
 
+.. _project_default_targets:
+
+Default targets
+---------------
+When running BuildStream commands from a project directory or subdirectory
+without specifying any target elements on the command line, the default targets
+of the project will be used.  The default targets can be configured in the
+``defaults`` section as follows:
+
+.. code:: yaml
+
+   defaults:
+
+     targets:
+     - app.bst
+
+If no default targets are configured in ``project.conf``, BuildStream commands
+will default to all ``.bst`` files in the configured element path.
+
+Commands that cannot support junctions as target elements (``bst build``,
+``bst artifact push``, and ``bst artifact pull``) ignore junctions in the list
+of default targets.
+
+When running BuildStream commands from a workspace directory (that is not a
+BuildStream project directory), project default targets are not used and the
+workspace element will be used as the default target instead.
+
+.. note::
+
+   The ``targets`` configuration is available since :ref:`format version 21 <project_format_version>`
+
+
 .. _project_builtin_defaults:
 
 Builtin defaults

[Tom Pollard]

Looks good to me, maybe it's worth pointing out that commands that expect a single target element can only make use of the default target if ran inside a workspace?