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
 

docs/start.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

mkdocs.yml

@@ -48,8 +48,15 @@ extra:
     - icon: fontawesome/brands/python
       link: https://pypi.org/project/xrlint/
 
+watch:
+  - xrlint
+
 plugins:
   - search
+  # Build rule reference page
+  - gen-files:
+      scripts:
+        - docs/mkruleref.py
   - autorefs
   - mkdocstrings:
       handlers:

pyproject.toml

@@ -90,7 +90,8 @@ doc = [
   "mkdocs-autorefs",
   "mkdocs-material",
   "mkdocstrings",
-  "mkdocstrings-python"
+  "mkdocstrings-python",
+  "mkdocs-gen-files",
 ]
 
 [project.urls]