items: Improve substitution error messages

3 files changed, 15 insertions, 3 deletions

diff --git a/rtemsspec/items.py b/rtemsspec/items.py
index 0e22f640..32a9eeaa 100644
--- a/rtemsspec/items.py
+++ b/rtemsspec/items.py
@@ -506,8 +506,16 @@ class ItemMapper:
         """
         if not text:
             return ""
-        context = _ItemMapperContext(self, item, prefix, self._recursive)
-        return ItemTemplate(text).substitute(context)
+        try:
+            context = _ItemMapperContext(self, item, prefix, self._recursive)
+            return ItemTemplate(text).substitute(context)
+        except Exception as err:
+            spec = self._item.spec if item is None else item.spec
+            if prefix is None:
+                prefix = "/".join(self._prefix)
+            msg = (f"substitution for {spec} using prefix '{prefix}' "
+                   f"failed for text: {text}")
+            raise ValueError(msg) from err
 
 
 class _SpecType(NamedTuple):
diff --git a/rtemsspec/tests/test_content_sphinx.py b/rtemsspec/tests/test_content_sphinx.py
index 70ed6226..e45703a9 100644
--- a/rtemsspec/tests/test_content_sphinx.py
+++ b/rtemsspec/tests/test_content_sphinx.py
@@ -276,7 +276,8 @@ def test_substitute(tmpdir):
                                                     with_spec_types=True)
     item_cache = ItemCache(config)
     mapper = SphinxMapper(item_cache["/x"])
-    with pytest.raises(KeyError):
+    match = r"substitution for spec:/x using prefix '' failed for text: \${x:/y}"
+    with pytest.raises(ValueError, match=match):
         mapper.substitute("${x:/y}")
     assert mapper.substitute("${x:/term}") == ":term:`y`"
     assert mapper.substitute("${x:/plural}") == ":term:`ys <y>`"
diff --git a/rtemsspec/tests/test_items_itemcache.py b/rtemsspec/tests/test_items_itemcache.py
index 922e6220..b1aba815 100644
--- a/rtemsspec/tests/test_items_itemcache.py
+++ b/rtemsspec/tests/test_items_itemcache.py
@@ -158,6 +158,9 @@ def test_item_mapper(tmpdir):
     recursive_mapper = ItemMapper(item, recursive=True)
     assert recursive_mapper.substitute("${.:/r1/r2/r3}") == "foobar"
     assert recursive_mapper[".:/r1/r2/r3"] == "foobar"
+    match = r"substitution for spec:/p using prefix 'blub' failed for text: \${}"
+    with pytest.raises(ValueError, match=match):
+        mapper.substitute("${}", item, "blub")
 
 
 def test_empty_item_mapper():