deprecate non-list examples

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `ewokstasks` directive displays task tags.
 
+### Changed
+
+- `ewokstasks` directive: clear error for pydantic fields with non-list `examples`.
+
 ## [2.2.1] - 2026-04-21
 
 ### Fixed

src/ewokssphinx/ewoks_task_utils.py

@@ -123,7 +123,7 @@ def _parse_parameter_names(
 
 def _parse_pydantic_model(model: Type[BaseModel]) -> list[ParameterDescription]:
     return [
-        _parse_pydantic_field(name, field_info)
+        _parse_pydantic_field(model, name, field_info)
         for name, field_info in model.model_fields.items()
     ]
 
@@ -141,8 +141,15 @@ def _parse_doc(text) -> str:
     return inspect.cleandoc(text) if text else ""
 
 
-def _parse_pydantic_field(name: str, field_info: FieldInfo) -> ParameterDescription:
+def _parse_pydantic_field(
+    model: Type[BaseModel], name: str, field_info: FieldInfo
+) -> ParameterDescription:
     examples = getattr(field_info, "examples", None)
+    if examples is not None and not isinstance(examples, list):
+        raise TypeError(
+            f"'examples' of field '{name}' of '{qualname(model)}' must be a list, "
+            f"got {type(examples).__name__}"
+        )
     default = getattr(field_info, "default", None)
     if default is PydanticUndefined:
         default = None

src/ewokssphinx/tests/test_utils.py

@@ -1,6 +1,9 @@
+import pytest
 from pydantic import BaseModel
+from pydantic import Field
 
 from ewokssphinx.ewoks_task_utils import _extract_submodels
+from ewokssphinx.ewoks_task_utils import _parse_pydantic_model
 
 
 class Type1(BaseModel):
@@ -44,3 +47,11 @@ def test_extract_type_inputs():
         "ewokssphinx.tests.dummy_tasks_nested.Coordinates",
         "ewokssphinx.tests.dummy_tasks_nested.Planet",
     ]
+
+
+def test_parse_non_list_examples():
+    class Model(BaseModel):
+        resources: dict = Field(default={}, examples={"cpu": 0.5})
+
+    with pytest.raises(TypeError, match="resources"):
+        _parse_pydantic_model(Model)