[MAINT] use jinja in the macros

.github/workflows/validation.yml

@@ -27,10 +27,8 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - name: Install dependencies
-        run: npm install `cat npm-requirements.txt`
       - name: Run style checks
-        run: npx remark src/**/*.md --frail --rc-path .remarkrc
+        run: make remark
 
   # YAML
   yamllint:

.pre-commit-config.yaml

@@ -82,6 +82,7 @@ repos:
           - click
           - markdown-it-py
           - importlib_resources
+          - jinja2
           - pandas-stubs
           - pyparsing
           - pytest

Makefile

@@ -1,5 +1,3 @@
-.PHONY:  tools/contributors.tsv
-
 validate_citation_cff: CITATION.cff
 	cffconvert --validate
 
@@ -8,12 +6,13 @@ update_contributors:
 	python tools/print_contributors.py
 	yarn all-contributors generate
 
+.PHONY: runprettier
 runprettier:
 	prettier --write "src/schema/**/*.yaml"
 	python3 -m yamllint -f standard src/schema/ -c .yamllint.yml
 
+.PHONY: commitschema
 SCHEMA_CHANGES := $(shell git diff --name-only | grep src/schema/*.yaml)
-
 commitschema:
 	@echo SCHEMA_CHANGES $(SCHEMA_CHANGES)
 	git add src/schema/*.yaml && \
@@ -23,6 +22,9 @@ commitschema:
 
 formatschema: runprettier commitschema
 
-all:
+# check style of all markdown files
+node_modules: npm-requirements.txt
+	npm install `cat npm-requirements.txt`
 
-.PHONY: runprettier commitschema
+remark: node_modules
+	npx remark src/**/*.md --frail --rc-path .remarkrc

tools/schemacode/pyproject.toml

@@ -33,7 +33,8 @@ expressions = ["pyparsing"]
 render = [
     "tabulate",
     "pandas",
-    "markdown-it-py"
+    "markdown-it-py",
+    "jinja2"
 ]
 tests = [
     "bidsschematools[expressions,render]",

tools/schemacode/src/bidsschematools/render/templates/common_principle.jinja

@@ -0,0 +1,4 @@
+{% for principle in principles %}
+1. **{{ principle.display_name }}** - {{ principle.description }}
+
+{% endfor %}

tools/schemacode/src/bidsschematools/render/templates/entity_definition.jinja

@@ -0,0 +1,11 @@
+## {{ entity.name }}
+
+**Full name**: {{ entity.display_name }}
+
+**Format**: `{{ entity.name }}-<{{ entity_info.format }}>`
+
+{% if entity.allowed_values %}
+**Allowed values**: `{% for value in allowed_values %}{{ value }}{% if not loop.last %}, {% endif %}{% endfor %}`
+{% endif %}
+
+**Definition**: {{ description }}

tools/schemacode/src/bidsschematools/render/text.py

@@ -1,6 +1,9 @@
 """Functions for rendering portions of the schema as text."""
 
+from pathlib import Path
+
 import yaml
+from jinja2 import Template
 from markdown_it import MarkdownIt
 
 from bidsschematools.render import utils
@@ -49,37 +52,32 @@ def make_entity_definitions(schema, src_path=None):
     text = ""
     for entity in entity_order:
         entity_info = entity_definitions[entity]
-        entity_text = _make_entity_definition(entity, entity_info)
-        text += "\n" + entity_text
+        text += _make_entity_definition(entity_info)
 
-    text = text.replace("SPEC_ROOT", utils.get_relpath(src_path))
-    return text
+    return text.replace("SPEC_ROOT", utils.get_relpath(src_path))
 
 
-def _make_entity_definition(entity, entity_info):
-    """Describe an entity."""
-    entity_shorthand = entity_info["name"]
-    text = ""
-    text += f"## {entity_shorthand}"
-    text += "\n\n"
-    text += f"**Full name**: {entity_info['display_name']}"
-    text += "\n\n"
-    text += f"**Format**: `{entity_info['name']}-<{entity_info.get('format', 'label')}>`"
-    text += "\n\n"
-    if "enum" in entity_info.keys():
-        allowed_values = []
+def _make_entity_definition(entity_info):
+    """Generate markdown description for an entity."""
+    # Prepare data for template rendering
+    entity_info.format = entity_info.get("format", "label")
+
+    # Prepare enum values if present
+    allowed_values = []
+    if "enum" in entity_info:
         for value in entity_info["enum"]:
             if isinstance(value, str):
                 allowed_values.append(value)
-            else:
+            elif isinstance(value, dict) and "name" in value:
                 allowed_values.append(value["name"])
+            else:
+                allowed_values.append(str(value))  # Fallback to string
+    entity_info.allowed_values = allowed_values
 
-        text += f"**Allowed values**: `{'`, `'.join(allowed_values)}`"
-        text += "\n\n"
-
-    description = entity_info["description"]
-    text += f"**Definition**: {description}"
-    return text
+    with (Path(__file__).parent / "templates/entity_definiiton.jinja").open("r") as f:
+        template_str = f.read()
+    template = Template(template_str)
+    return template.render(entity=entity_info)
 
 
 def make_glossary(schema, src_path=None):
@@ -504,21 +502,19 @@ def define_common_principles(schema, src_path=None):
     string : str
         The definitions of the common principles in a multiline string.
     """
-    string = ""
+    # reorder the principles according to the order
     common_principles = schema["objects"]["common_principles"]
     order = schema["rules"]["common_principles"]
-    for i_prin, principle in enumerate(order):
-        principle_name = common_principles[principle]["display_name"]
-        substring = (
-            f"{i_prin + 1}. **{principle_name}** - {common_principles[principle]['description']}"
-        )
-        string += substring
-        if i_prin < len(order) - 1:
-            string += "\n\n"
+    principles = []
+    for principle in order:
+        principles.append(common_principles.get(principle))
 
-    string = string.replace("SPEC_ROOT", utils.get_relpath(src_path))
+    with (Path(__file__).parent / "templates/common_principle.jinja").open("r") as f:
+        template_str = f.read()
+    template = Template(template_str)
+    text = template.render(principles=principles)
 
-    return string
+    return text.replace("SPEC_ROOT", src_path)
 
 
 def define_allowed_top_directories(schema, src_path=None) -> str: