Merge branch 'jennis/filter-docs' into 'master'

Improve our filter documentation

Closes #278

See merge request BuildStream/buildstream!1112

2 files changed, 124 insertions, 21 deletions

diff --git a/buildstream/plugins/elements/filter.py b/buildstream/plugins/elements/filter.py
index b2c292261..b3632f265 100644
--- a/buildstream/plugins/elements/filter.py
+++ b/buildstream/plugins/elements/filter.py
@@ -20,25 +20,127 @@
 """
 filter - Extract a subset of files from another element
 =======================================================
-This filters another element by producing an output that is a subset of
-the filtered element.
+Filter another element by producing an output that is a subset of
+the parent element's output. Subsets are defined by the parent element's
+:ref:`split rules <public_split_rules>`.
 
-To specify the element to filter, specify it as the one and only build
-dependency to filter. See :ref:`Dependencies <format_dependencies>`
-for what dependencies are and how to specify them.
+Overview
+--------
+A filter element must have exactly one *build* dependency, where said
+dependency is the 'parent' element which we would like to filter.
+Runtime dependencies may also be specified, which can be useful to propagate
+forward from this filter element onto its reverse dependencies.
+See :ref:`Dependencies <format_dependencies>` to see how we specify dependencies.
 
-Dependencies aside from the filtered element may be specified, but
-they must be runtime dependencies only. This can be useful to propagate
-runtime dependencies forward from this filter element onto its reverse
-dependencies.
+When workspaces are opened, closed or reset on a filter element, or this
+element is tracked, the filter element will transparently pass on the command
+to its parent element (the sole build-dependency).
 
-When workspaces are opened, closed or reset on this element, or this
-element is tracked, instead of erroring due to a lack of sources, this
-element will transparently pass on the command to its sole build-dependency.
+Example
+-------
+Consider a simple import element, ``import.bst`` which imports the local files
+'foo', 'bar' and 'baz' (each stored in ``files/``, relative to the project's root):
 
-The default configuration and possible options are as such:
-  .. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml
-     :language: yaml
+.. code:: yaml
+
+   kind: import
+
+   # Specify sources to import
+   sources:
+   - kind: local
+     path: files
+
+   # Specify public domain data, visible to other elements
+   public:
+     bst:
+       split-rules:
+         foo:
+         - /foo
+         bar:
+         - /bar
+
+.. note::
+
+   We can make an element's metadata visible to all reverse dependencies by making use
+   of the ``public:`` field. See the :ref:`public data documentation <format_public>`
+   for more information.
+
+In this example, ``import.bst`` will serve as the 'parent' of the filter element, thus
+its output will be filtered. It is important to understand that the artifact of the
+above element will contain the files: 'foo', 'bar' and 'baz'.
+
+Now, to produce an element whose artifact contains the file 'foo', and exlusively 'foo',
+we can define the following filter, ``filter-foo.bst``:
+
+.. code:: yaml
+
+   kind: filter
+
+   # Declare the sole build-dependency of the filter element
+   depends:
+   - filename: import.bst
+     type: build
+
+   # Declare a list of domains to include in the filter's artifact
+   config:
+     include:
+     - foo
+
+.. note::
+
+   We can also specify build-dependencies with a 'build-depends' field which has been
+   available since :ref:`format version 14 <project_format_version>`. See the
+   :ref:`Build-Depends documentation <format_build_depends>` for more detail.
+
+It should be noted that an 'empty' ``include:`` list would, by default, include all
+split-rules specified in the parent element, which, in this example, would be the
+files 'foo' and 'bar' (the file 'baz' was not covered by any split rules).
+
+Equally, we can use the ``exclude:`` statement to create the same artifact (which
+only contains the file 'foo') by declaring the following element, ``exclude-bar.bst``:
+
+.. code:: yaml
+
+   kind: filter
+
+   # Declare the sole build-dependency of the filter element
+   depends:
+   - filename: import.bst
+     type: build
+
+   # Declare a list of domains to exclude in the filter's artifact
+   config:
+     exclude:
+     - bar
+
+In addition to the ``include:`` and ``exclude:`` fields, there exists an ``include-orphans:``
+(Boolean) field, which defaults to ``False``. This will determine whether to include files
+which are not present in the 'split-rules'. For example, if we wanted to filter out all files
+which are not included as split rules we can define the following element, ``filter-misc.bst``:
+
+.. code:: yaml
+
+   kind: filter
+
+   # Declare the sole build-dependency of the filter element
+   depends:
+   - filename: import.bst
+     type: build
+
+   # Filter out all files which are not declared as split rules
+   config:
+     exclude:
+     - foo
+     - bar
+     include-orphans: True
+
+The artifact of ``filter-misc.bst`` will only contain the file 'baz'.
+
+Below is more information regarding the the default configurations and possible options
+of the filter element:
+
+.. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml
+   :language: yaml
 """
 
 from buildstream import Element, ElementError, Scope
diff --git a/buildstream/plugins/elements/filter.yaml b/buildstream/plugins/elements/filter.yaml
index 627a00cce..78465a183 100644
--- a/buildstream/plugins/elements/filter.yaml
+++ b/buildstream/plugins/elements/filter.yaml
@@ -2,20 +2,21 @@
 # Filter element configuration
 config:
 
-  # A list of domains to include from each artifact, as
-  # they were defined in the element's 'split-rules'.
+  # A list of domains to include in each artifact, as
+  # they were defined as public data in the parent
+  # element's 'split-rules'.
   #
   # Since domains can be added, it is not an error to
   # specify domains which may not exist for all of the
   # elements in this composition.
   #
   # The default empty list indicates that all domains
-  # from each dependency should be included.
+  # of the parent's artifact should be included.
   #
   include: []
 
   # A list of domains to exclude from each artifact, as
-  # they were defined in the element's 'split-rules'.
+  # they were defined in the parent element's 'split-rules'.
   #
   # In the case that a file is spoken for by a domain
   # in the 'include' list and another in the 'exclude'
@@ -23,7 +24,7 @@ config:
   exclude: []
 
   # Whether to include orphan files which are not
-  # included by any of the 'split-rules' present on
-  # a given element.
+  # included by any of the 'split-rules' present in
+  # the parent element.
   #
   include-orphans: False