filter.py/filter.yaml: Documentation improvements

"""

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 <format_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 <public_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 <format_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

# 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 filter element will fail when trying to include

  # domains that do not exist.

  #

  # 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'

  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