Humanize custom item names

build/scripts/build_readme_impl.py

@@ -69,6 +69,10 @@ def render_path_for_model(model_ref: str) -> Path | None:
     return Path("renders") / namespace / Path(path).with_suffix(".png")
 
 
+def display_name_for_item(item_name: str) -> str:
+    return item_name.replace("_", " ").title()
+
+
 def collect_renameable_items(pack_root: Path) -> list[dict[str, Any]]:
     item_files = sorted(pack_root.glob("assets/*/items/*.json"))
     records: list[dict[str, Any]] = []
@@ -154,13 +158,15 @@ def build_markdown(records: list[dict[str, Any]]) -> str:
     lines.append("Sections are sorted by the item they are generated from.")
 
     for record in records:
-        lines.append(f"## {record['item']}")
+        display_name = display_name_for_item(record["item"])
+
+        lines.append(f"## {display_name}")
         lines.append("")
         lines.append(f"- Generated from: `{record['source_file']}`")
         lines.append(f"- Fallback model: `{record['fallback_model']}`")
         if record["render_path"]:
             lines.append(f"- Base render: `{record['render_path']}`")
-            lines.append(f"  - Preview: <img src=\"{record['render_path']}\" alt=\"{record['item']}\" width=\"160\" />")
+            lines.append(f"  - Preview: <img src=\"{record['render_path']}\" alt=\"{display_name}\" width=\"160\" />")
         else:
             lines.append("- Base render: not present yet")
 
@@ -248,7 +254,9 @@ def build_namespace_catalog(records: list[dict[str, Any]], namespace: str) -> st
     lines.append("")
 
     for record in namespace_records:
-        lines.append(f"## {record['item']}")
+        display_name = display_name_for_item(record["item"])
+
+        lines.append(f"## {display_name}")
         lines.append("")
         lines.append(f"- Generated from: `{record['source_file']}`")
         lines.append(f"- Fallback model: `{record['fallback_model']}`")
@@ -286,6 +294,8 @@ def build_html(records: list[dict[str, Any]]) -> str:
 
     for record in records:
         preview_items: list[str] = []
+        display_name = display_name_for_item(record["item"])
+
         for case in record["cases"]:
             render_path = case["render_path"]
             if render_path:
@@ -303,7 +313,7 @@ def build_html(records: list[dict[str, Any]]) -> str:
 
         render_path = record["render_path"]
         if render_path:
-            hero = f'<img src="{html.escape(render_path)}" alt="{html.escape(record["item"])}" />'
+            hero = f'<img src="{html.escape(render_path)}" alt="{html.escape(display_name)}" />'
         else:
             hero = '<div class="hero-missing">no base render</div>'
 
@@ -311,7 +321,7 @@ def build_html(records: list[dict[str, Any]]) -> str:
             "<section class='card'>"
             f"<div class='hero'>{hero}</div>"
             "<div class='meta'>"
-            f"<h2>{html.escape(record['item'])}</h2>"
+            f"<h2>{html.escape(display_name)}</h2>"
             f"<p class='source'>{html.escape(record['source_file'])}</p>"
             f"<p class='fallback'>Fallback model: {html.escape(record['fallback_model'])}</p>"
             f"<div class='variants'>{''.join(preview_items)}</div>"