Added more documentation

CERT-Polska · Mar 11, 2024 · 0331d9f · 0331d9f
1 parent 60d1280
commit 0331d9f
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 1 deletion.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
-Sphinx==4.5.0
+Sphinx==5.3.0
 sphinx-autodoc-annotation==1.0.post1
 sphinx-autodoc-typehints==1.10.3
 sphinx-rtd-theme==0.5.0

diff --git a/docs/task_headers_payloads.rst b/docs/task_headers_payloads.rst
@@ -107,6 +107,18 @@ Filter logic can be used to fulfill specific use-cases:
 ``[{"foo": "!*"}]``                   'foo' header must be not defined.
 ====================================  ==============================================================================
 
+Excluding (negated) filters come with specific corner-cases. Regular filters require specific value to be defined in header, while
+negated filters are accepting all possible values except specified in filter.
+
+==================================================================================  =============================================================================================================================================
+   ``filters`` value                                                                  Meaning
+----------------------------------------------------------------------------------  ---------------------------------------------------------------------------------------------------------------------------------------------
+``[{"type": "sample", "stage": "!*"}]``                                             matches only tasks that have type 'sample' but no 'stage' key
+``[{"platform": "!linux"}, {"platform": "!windows"}]``                              matches **all** tasks (even with no headers) but not these with platform 'linux' or 'windows'
+``[{"foo": "bar", "platform": "!linux"}, {"foo": "bar", "platform": "!windows"}]``  'foo' header is required and must have 'bar' value, but platform can't be 'linux' or 'windows'
+``[{"foo": "bar", "platform": "!linux"}, {"foo": "baz", "platform": "!windows"}]``  'foo' header is required and must have 'bar' value and no 'linux' in platform key, or foo must be 'baz', but then platform can't be 'windows'
+==================================================================================  =============================================================================================================================================
+
 .. warning::
 
     It's recommended to use only strings in filter and header values