Added examples page

CHANGES.md

@@ -2,6 +2,8 @@
 
 ## Version 0.5.1 (in development)
 
+- Enhanced documentation by a new page that compiles
+  the code examples in the `examples` folder.
 
 ## Version 0.5.0 (from 2025-02-13)
 

docs/api.md

@@ -46,18 +46,26 @@ Note:
   the `xrlint.all` convenience module exports all of the above from a 
   single module.
 
+## CLI API
+
 ::: xrlint.cli.engine.XRLint
 
+## Linter API
+
 ::: xrlint.linter.new_linter
 
 ::: xrlint.linter.Linter
 
+## Plugin API
+
 ::: xrlint.plugin.new_plugin
 
 ::: xrlint.plugin.Plugin
 
 ::: xrlint.plugin.PluginMeta
 
+## Configuration API
+
 ::: xrlint.config.Config
 
 ::: xrlint.config.ConfigObject
@@ -66,6 +74,8 @@ Note:
 
 ::: xrlint.config.ConfigObjectLike
 
+## Rule API
+
 ::: xrlint.rule.define_rule
 
 ::: xrlint.rule.Rule
@@ -78,6 +88,8 @@ Note:
 
 ::: xrlint.rule.RuleExit
 
+## Dataset Node API
+
 ::: xrlint.node.Node
 
 ::: xrlint.node.XarrayNode
@@ -92,6 +104,8 @@ Note:
 
 ::: xrlint.node.AttrNode
 
+## Processor API
+
 ::: xrlint.processor.define_processor
 
 ::: xrlint.processor.Processor
@@ -100,12 +114,16 @@ Note:
 
 ::: xrlint.processor.ProcessorOp
 
+## Result API
+
 ::: xrlint.result.Result
 
 ::: xrlint.result.Message
 
 ::: xrlint.result.Suggestion
 
+## Testing API
+
 ::: xrlint.testing.RuleTester
 
 ::: xrlint.testing.RuleTest

docs/examples.md

@@ -0,0 +1,35 @@
+# Examples
+
+## Configuration
+
+::: examples.plugin_config
+
+    options:
+      members: false
+
+Source code: [`examples/plugin_config.py`](https://github.com/bcdev/xrlint/blob/main/examples/plugin_config.py)
+
+::: examples.virtual_plugin_config
+
+    options:
+      members: false
+
+Source code: [`examples/virtual_plugin_config.py`](https://github.com/bcdev/xrlint/blob/main/examples/virtual_plugin_config.py)
+
+## Developing rules
+
+::: examples.rule_testing
+
+    options:
+      members: false
+
+Source code: [`examples/rule_testing.py`](https://github.com/bcdev/xrlint/blob/main/examples/rule_testing.py)
+
+## API usage
+
+::: examples.check_s3_bucket
+
+    options:
+      members: false
+
+Source code: [`examples/check_s3_bucket.py`](https://github.com/bcdev/xrlint/blob/main/examples/check_s3_bucket.py)

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
   - Rule Reference: rule-ref.md
   - CLI: cli.md
   - Python API: api.md
+  - Examples: examples.md
   - About: about.md
 
 theme:
@@ -55,9 +56,16 @@ plugins:
         python:
           options:
             docstring_style: google
+            docstring_section_style: list
+            show_object_full_path: true
             show_root_toc_entry: true
             show_root_heading: true
             show_source: true
-            heading_level: 2
+            show_category_heading: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            heading_level: 3
             annotations_path: brief
             members_order: source
+            extra:
+              show_overloads: true