docs(prometheus): writing a widget template, every block, and the format reference (#5694)

docs/plugins/prometheus-widgets.md covers:
- where templates live and how to copy one in, duplicate, export and share;
- a first template, walked through;
- each block (states with its deadlines, values, times, table, info) with an
  example;
- the format reference: keys, units, spans, limits, what the checker refuses;
- the Fabled Archives template, block by block, with what it leaves out and
  why.

Linked from the README, the plugin guide, the editor and template_format.
tests/plugins/prometheus/test_widget_guide.py checks every YAML example in the
guide against the checker, so the guide can't drift from the format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/plugins/prometheus/test_widget_guide.py

@@ -0,0 +1,42 @@
+"""docs/plugins/prometheus-widgets.md (#5694): every YAML example in the
+guide passes the checker, so the guide can't drift from the format."""
+import re
+import textwrap
+
+from plugins.prometheus.template_format import check
+from tests._templates import REPO
+
+GUIDE = REPO / "docs" / "plugins" / "prometheus-widgets.md"
+_FENCE = re.compile(r"```yaml\n(.*?)```", re.S)
+
+
+def examples(text: str) -> list[str]:
+    """Each fenced YAML example as a whole template: a block on its own is
+    wrapped in a name, a version and a blocks list."""
+    out = []
+    for body in _FENCE.findall(text):
+        if body.startswith("name:"):
+            out.append(body)
+        else:
+            out.append("name: Example\nversion: 1\nblocks:\n" + textwrap.indent(body, "  "))
+    return out
+
+
+def test_the_guard_can_fail():
+    bad = examples("```yaml\n- states: {metric: x_state, healthy: [ok], colour: red}\n```")
+    assert len(bad) == 1
+    try:
+        check(bad[0])
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("an unknown key passed the checker")
+
+
+def test_every_example_in_the_guide_is_a_template():
+    found = examples(GUIDE.read_text())
+    assert len(found) >= 6, len(found)       # the first template, then one per block kind
+    kinds = set()
+    for text in found:
+        kinds.update(b.kind for b in check(text).blocks)
+    assert kinds == {"states", "values", "times", "table", "info"}