Automatically update rule docs

Author: abkfenris

CONTRIBUTING.md

@@ -85,3 +85,15 @@ The rule naming conventions for XRLint are based ESLint:
   in a dedicated module under `tests`, i.e., `tests/rules/test_<rule>`. 
   Consider using `xrlint.testing.RuleTester` which can save a lot of
   time and is used for almost all in-built rules.
+
+## Contributing an XRLint Plugin
+
+New plugins should be added to the `xrlint.rules` entry point table, which will cause them to be automatically loaded by XRLint, and to be included in the rule documentation.
+
+```toml
+# pyproject.toml
+[project.entry-points."xrlint.rules"]
+core = "xrlint.plugins.core"
+xcube = "xrlint.plugins.xcube"
+acdd = "xrlint.plugins.acdd"
+```

docs/about.md

@@ -72,12 +72,7 @@ mkdocs serve
 mkdocs gh-deploy
 ```
 
-The rule reference page is generated by a script called `mkruleref.py`.
-After changing or adding a rule, make sure you recreate the page:
-
-```bash
-python -m mkruleref
-```
+The rule reference page is generated by a script called `docs/mkruleref.py` which is called by mkdocs during build.
 
 ## License
 

mkruleref.py docs/mkruleref.pymkruleref.py renamed to docs/mkruleref.py

@@ -4,6 +4,7 @@
 
 from xrlint.plugin import Plugin
 from xrlint.rule import RuleConfig
+from xrlint.config import plugins_from_entry_points
 
 # for icons, see
 # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
@@ -25,26 +26,27 @@
 
 
 def write_rule_ref_page():
-    import xrlint.plugins.core
-    import xrlint.plugins.xcube
-    import xrlint.plugins.acdd
-
-    core = xrlint.plugins.core.export_plugin()
-    xcube = xrlint.plugins.xcube.export_plugin()
-    acdd = xrlint.plugins.acdd.export_plugin()
-    with open("docs/rule-ref.md", "w") as stream:
+    import mkdocs_gen_files
+
+    plugins = plugins_from_entry_points()
+
+    print(f"Generating rule reference for discovered plugins: {list(plugins.keys())}")
+
+    with mkdocs_gen_files.open("rule-ref.md", "w") as stream:
         stream.write("# Rule Reference\n\n")
         stream.write(
             "This page is auto-generated from XRLint's builtin"
-            " rules (`python -m mkruleref`).\n"
+            " rules.\n"
             "New rules will be added by upcoming XRLint releases.\n\n"
         )
-        stream.write("## Core Rules\n\n")
-        write_plugin_rules(stream, core)
-        stream.write("## xcube Rules\n\n")
-        write_plugin_rules(stream, xcube)
-        stream.write("## ACDD Rules\n\n")
-        write_plugin_rules(stream, acdd)
+        for plugin_name in sorted(plugins.keys()):
+            plugin = plugins[plugin_name]
+            stream.write(f"## {plugin.meta.name} Rules\n\n")
+            if plugin.meta.ref:
+                stream.write(f"- `{plugin.meta.ref.removesuffix(':export_plugin')}`\n")
+            if plugin.meta.docs_url:
+                stream.write(f"- [Documentation]({plugin.meta.docs_url})\n\n")
+            write_plugin_rules(stream, plugin)
 
 
 def write_plugin_rules(stream, plugin: Plugin):
@@ -86,5 +88,4 @@ def get_plugin_rule_configs(plugin: Plugin) -> dict[str, dict[str, RuleConfig]]:
     return config_rules
 
 
-if __name__ == "__main__":
-    write_rule_ref_page()
+write_rule_ref_page()

docs/rule-ref.md

@@ -64,14 +64,16 @@ rule configurations:
     grid-mappings: error
 ```
 
-You can add rules from plugins as well:
-
 !!! note inline end "Built in and auto-loading plugins"
 
     The included plugins (such as `xcube` in the example configs here) and those from external libraries that are findable via [entry points](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) do not need to be explicitly loaded.
 
     Run `xrlint --print-config <dataset>` to view the loaded plugins and configured rules.
 
+    Custom plugins, or those that are not loadable via entry points will need to be explcitly loaded via the plugins object.
+
+You can add rules from plugins as well:
+
 ```yaml
 - recommended
 - plugins:
@@ -83,8 +85,9 @@ And customize its rules, if desired:
 
 ```yaml
 - recommended
-- plugins:
-    xcube: xrlint.plugins.xcube
+# Explicit loading of included plugins is unneeded, see note
+# - plugins:
+#    xcube: xrlint.plugins.xcube
 - xcube/recommended  
 - rules:
     xcube/grid-mapping-naming: off