From dbb3d2329654f9f0896f53316fe74f7c57d4b6b7 Mon Sep 17 00:00:00 2001 From: James Ennis Date: Mon, 28 Jan 2019 12:51:49 +0000 Subject: filter.py/filter.yaml: Documentation improvements --- buildstream/plugins/elements/filter.py | 30 +++++++++++++++--------------- buildstream/plugins/elements/filter.yaml | 13 +++++++------ 2 files changed, 22 insertions(+), 21 deletions(-) diff --git a/buildstream/plugins/elements/filter.py b/buildstream/plugins/elements/filter.py index b2c292261..b8b9c749d 100644 --- a/buildstream/plugins/elements/filter.py +++ b/buildstream/plugins/elements/filter.py @@ -20,21 +20,21 @@ """ 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. - -To specify the element to filter, specify it as the one and only build -dependency to filter. See :ref:`Dependencies ` -for what dependencies are and how to specify them. - -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 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. +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 `. + +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 ` to see how we specify 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). The default configuration and possible options are as such: .. literalinclude:: ../../../buildstream/plugins/elements/filter.yaml 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 -- cgit v1.2.1