Improve guide on filtering tests.

docs/features/directory.conf

@@ -6,7 +6,6 @@ laika.navigationOrder = [
  resources.md,
  global_resources.md,
  logging.md,
- tagging.md,
  scalacheck.md,
  discipline.md,
  parallelism.md,

docs/features/filtering.md

@@ -1,7 +1,9 @@
 Filtering tests
 ===============
 
-When using the IOSuite variants, the user can call `sbt`'s test command as such:
+## Running a subset of tests
+
+You can run a set of tests with `sbt` using the `testOnly` command:
 
 ``` 
 > testOnly -- -o *foo*
@@ -12,3 +14,72 @@ This filter will prevent the execution of any test that doesn't contain the stri
 ```
 fooPackage.FooSuite.foo
 ```
+
+## Running a single test
+
+You can run a single test in a suite by appending `only` to the test name:
+
+```scala mdoc
+import weaver._
+
+object ExampleSuite extends FunSuite {
+
+  test("Only run this test".only) {
+    expect.eql(1, 2)
+  }
+
+  test("This test will not be run") {
+      expect.eql(1, 1)
+  }
+}
+```
+
+## Ignoring tests
+
+You can mark a test as ignored by appending `ignore` to the test name. The test will not be run as part of your test suite.
+
+```scala mdoc
+import weaver._
+
+object IgnoreSuite extends FunSuite {
+
+  test("This test is not run".ignore) {
+    expect.eql(1, 2)
+  }
+  test("This test is run") {
+    expect.eql(1, 1)
+  }
+}
+```
+
+### Example report
+
+```scala mdoc:passthrough 
+println(weaver.docs.Output.runSuites(IgnoreSuite))
+```
+
+## Dynamically ignoring tests
+
+You can also dynamically mark tests as ignored using the `ignore` function:
+
+```scala mdoc
+import weaver._
+import cats.effect.IO
+import cats.syntax.all._
+
+object DynamicIgnoreSuite extends SimpleIOSuite {
+
+  test("Only on CI") {
+    for {
+      onCI <- IO(sys.env.get("CI").isDefined)
+      _    <- ignore("not on CI").unlessA(onCI)
+    } yield expect.eql(1, 2)
+  }
+}
+```
+
+### Example report
+
+```scala mdoc:passthrough 
+println(weaver.docs.Output.runSuites(DynamicIgnoreSuite))
+```