updated examples

examples/check_s3_bucket.py

@@ -2,6 +2,11 @@
 #  This software is distributed under the terms and conditions of the
 #  MIT license (https://mit-license.org/).
 
+"""
+This code example shows how to use the high-level
+Python API to validate the contents of an S3 bucket.
+"""
+
 import xrlint.all as xrl
 
 URL = "s3://xcube-test/"

examples/plugin_config.py

@@ -1,11 +1,19 @@
+#  Copyright © 2025 Brockmann Consult GmbH.
+#  This software is distributed under the terms and conditions of the
+#  MIT license (https://mit-license.org/).
+
 """
 This configuration example shows how to define and use a plugin
 using the `Plugin` class and its `define_rule()` decorator method.
-"""
 
-#  Copyright © 2025 Brockmann Consult GmbH.
-#  This software is distributed under the terms and conditions of the
-#  MIT license (https://mit-license.org/).
+You can use this example directly via the Python API by passing it's
+exported configuration to an instance of the `Linter` class or use
+the XRLint CLI:
+
+```bash
+xrlint -c examples/plugin_config.py <OPTIONS> <FILES>
+```
+"""
 
 from xrlint.node import DatasetNode
 from xrlint.plugin import new_plugin

examples/rule_testing.py

@@ -1,22 +1,32 @@
-"""
-This example demonstrates how to develop new rules.
-"""
-
 #  Copyright © 2025 Brockmann Consult GmbH.
 #  This software is distributed under the terms and conditions of the
 #  MIT license (https://mit-license.org/).
 
+"""
+This example demonstrates how to develop new rules.
+"""
+
 import xarray as xr
 
 from xrlint.node import DatasetNode
 from xrlint.rule import RuleContext, RuleOp, define_rule
 from xrlint.testing import RuleTest, RuleTester
 
 
+# ----------------------------------------------------
+# Place the rule implementation code in its own module
+# ----------------------------------------------------
+
+
 @define_rule("good-title")
 class GoodTitle(RuleOp):
     """Dataset title should be 'Hello World!'."""
 
+    # We just validate the dataset instance here. You can also implement
+    # the validation of other nodes in this class, e.g.,
+    # validate_datatree(), validate_variable(), validate_attrs(),
+    # and validate_attr().
+    #
     def validate_dataset(self, ctx: RuleContext, node: DatasetNode):
         good_title = "Hello World!"
         if node.dataset.attrs.get("title") != good_title:
@@ -26,27 +36,34 @@ def validate_dataset(self, ctx: RuleContext, node: DatasetNode):
             )
 
 
-# -----------------
-# In another module
-# -----------------
+# ---------------------------------------------------
+# Place the following rule test code in a test module
+# ---------------------------------------------------
 
 tester = RuleTester()
 
 valid_dataset = xr.Dataset(attrs=dict(title="Hello World!"))
 invalid_dataset = xr.Dataset(attrs=dict(title="Hello Hamburg!"))
 
-# Run test directly
+# You can use the tester to run a test directly
+#
 tester.run(
     "good-title",
     GoodTitle,
     valid=[RuleTest(dataset=valid_dataset)],
+    # We expect one message to be emitted
     invalid=[RuleTest(dataset=invalid_dataset, expected=1)],
 )
 
-# or define a test class derived from unitest.TestCase
+# ... or generate a test class that will be derived from `unitest.TestCase`.
+# This will provide you tooling support via your test runner, e.g., pytest,
+# as the tests in `valid` and `invalid` will be transformed into
+# test methods of the generated class.
+#
 GoodTitleTest = tester.define_test(
     "good-title",
     GoodTitle,
     valid=[RuleTest(dataset=valid_dataset)],
-    invalid=[RuleTest(dataset=invalid_dataset)],
+    # Note, here we expect a specific message to be emitted
+    invalid=[RuleTest(dataset=invalid_dataset, expected=["Attribute 'title' wrong."])],
 )

examples/virtual_plugin_config.py

@@ -1,12 +1,20 @@
+#  Copyright © 2025 Brockmann Consult GmbH.
+#  This software is distributed under the terms and conditions of the
+#  MIT license (https://mit-license.org/).
+
 """
 This configuration example demonstrates how to
 define and use "virtual" plugins. Such plugins
 can be defined inside a configuration item.
-"""
 
-#  Copyright © 2025 Brockmann Consult GmbH.
-#  This software is distributed under the terms and conditions of the
-#  MIT license (https://mit-license.org/).
+You can use this example directly via the Python API by passing it's
+exported configuration to an instance of the `Linter` class or use
+the XRLint CLI:
+
+```bash
+xrlint -c examples/virtual_plugin_config.py <OPTIONS> <FILES>
+```
+"""
 
 from xrlint.node import DatasetNode
 from xrlint.rule import RuleContext, RuleOp, define_rule