Add a documentation section on logical combinations of dependencies

Author: RKrahl

doc/examples/or_dependency.py

@@ -2,17 +2,6 @@
 from pytest_dependency import depends
 
 def depends_or(request, other, scope='module'):
-    """Add dependency on any of the other tests.
-
-    Call pytest.skip() unless a successful outcome of any of the tests
-    in `other` has been registered previously.  This helper is similar
-    to `pytest_dependency.depends()`.  It takes the same arguments.
-    But while `pytest_dependency.depends()` combines the tests in
-    `other` in an and-like manner, it skips the current test unless
-    all other tests did succeed, this function combines them in an
-    or-like manner, it runs the current test if at least one of the
-    other tests did succeed.
-    """
     item = request.node
     for o in other:
         try:

doc/src/advanced.rst

@@ -80,3 +80,31 @@ It requires the parameter values to be scalars that can easily be
 converted to strings.  And it will fail if the same list of parameters
 is passed to the same test more then once, because then, pytest will
 add an index to the name to disambiguate the parameter values.
+
+Logical combinations of dependencies
+------------------------------------
+
+The dependencies passed as in the `depends` argument to the
+:func:`pytest.mark.dependency` marker are combined in an and-like
+manner: the current test is skipped unless *all* dependencies did
+succeed.  Sometimes one may want to combine the dependencies in a
+different way.  This is not supported by pytest-dependency out of the
+box, but it is not difficult to implement.  Consider the following
+example:
+
+.. literalinclude:: ../examples/or_dependency.py
+
+The helper function `depends_or()` is similar to
+:func:`pytest_dependency.depends`, it takes the same arguments.  The
+only difference is that it combines the dependencies passed in the
+`other` argument in an or-like manner: the current test will be run if
+*at least one* of the other tests did succeed.
+
+The tests `test_c`, `test_d`, `test_e`, and `test_f` in this example
+all depend on two other tests.  Only `test_c` will be skipped, because
+all tests in its dependency list fail.  The other ones are run,
+because they have at least one succeeding test in their dependency
+list.
+
+Other logical combinations of dependencies are conceivable and may be
+implemented in a similar way, according to the use case at hand.