fix+enh: add empty_dirs option, fix documentation

Author: oesteban

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

@@ -233,6 +233,7 @@ def make_filename_template(
     n_dupes_to_combine=6,
     pdf_format=False,
     placeholders=False,
+    empty_dirs=None,
     **kwargs,
 ):
     """Create codeblocks containing example filename patterns for a given datatype.
@@ -263,10 +264,13 @@ def make_filename_template(
     placeholders : bool, optional
         If True, placeholder meta-entities will replace keyword-value entities in the
         filename.
-        If `dstype` is `"raw"`, the placeholder meta-entity is `<matches>`.
-        If `dstype` is `"derivatives"`, the placeholder meta-entity is `<source_entities>`.
+        If ``dstype`` is ``"raw"``, the placeholder meta-entity is ``<matches>``.
+        If ``dstype`` is ``"derivatives"``, the placeholder meta-entity is ``<source_entities>``.
         Default is False.
-    source_entities : bool
+    empty_dirs: bool, optional
+        If False, empty datatype directories are not included. If ``placeholders`` is True,
+        this option is set False.
+        Default is True.
 
     Other Parameters
     ----------------
@@ -318,6 +322,20 @@ def make_filename_template(
         for datatype in rule.datatypes:
             file_groups.setdefault(datatype, []).append(rule)
 
+    if placeholders:
+        empty_dirs = False if empty_dirs is None else empty_dirs
+        metaentity_name = "matches" if dstype == "raw" else "source_entities"
+        ent_string = (
+            lt
+            + utils._link_with_html(
+                metaentity_name,
+                html_path=GLOSSARY_PATH + ".html",
+                heading=f"{metaentity_name}-metaentities",
+                pdf_format=pdf_format,
+            )
+            + gt
+        )
+
     for datatype in sorted(file_groups):
         group_lines = []
         datatype_string = utils._link_with_html(
@@ -328,19 +346,6 @@ def make_filename_template(
         )
         group_lines.append(f"\t\t{datatype_string}/")
 
-        if placeholders:
-            metaentity_name = "matches" if dstype == "raw" else "source_entities"
-            ent_string = (
-                lt
-                + utils._link_with_html(
-                    metaentity_name,
-                    html_path=GLOSSARY_PATH + ".html",
-                    heading=f"{metaentity_name}-metaentities",
-                    pdf_format=pdf_format,
-                )
-                + gt
-            )
-
         # Unique filename patterns
         for group in file_groups[datatype]:
             if not placeholders:
@@ -439,8 +444,9 @@ def make_filename_template(
                 for extension in sorted(extensions)
             )
 
-            if placeholders and len(group_lines) == 1:
-                continue
+        # If the datatype does not have any files, skip
+        if empty_dirs is False and len(group_lines) == 1:
+            continue
 
         lines.extend(group_lines)
 

tools/schemacode/src/bidsschematools/tests/test_render_text.py

@@ -98,22 +98,71 @@ def test_make_filename_template(schema_obj, schema_dir, placeholders):
 
     datatype_count = len(datatypes)
     datatype_bases = [f"        {i}/" for i in datatypes]
-    datatype_level = False
     datatype_file_start = (
         "            sub-<label>" if not placeholders else "            <matches>_"
     )
     datatype_bases_found = 0
+    template_started = False
     for line in filename_template.split("\n"):
-        if datatype_level:
-            # Is there at least one file pattern per datatype?
-            assert line.startswith(datatype_file_start)
-            datatype_level = False
+        if "```" in line:
+            if template_started:
+                break
+
+            template_started = True
+            continue
+
+        if not template_started:
+            continue
+
+        if line.startswith("sub-<label>"):
+            continue
+        if line.startswith("    [ses-<label>/]"):
+            continue
+
         if line in datatype_bases:
-            datatype_level = True
             datatype_bases_found += 1
+        else:
+            assert line.startswith(datatype_file_start)
+
     # Are all datatypes listed?
     assert datatype_bases_found == datatype_count
 
+    # Restrict (a little) the datatype bases
+    filename_template = text.make_filename_template(
+        "raw",
+        schema_obj,
+        suffixes=["events"],
+        placeholders=placeholders,
+        empty_dirs=False,
+        pdf_format=True,
+    )
+
+    datatype_bases_found = 0
+    template_started = False
+    for line in filename_template.split("\n"):
+        if "```" in line:
+            if template_started:
+                break
+
+            template_started = True
+            continue
+
+        if not template_started:
+            continue
+
+        if line.startswith("sub-<label>"):
+            continue
+        if line.startswith("    [ses-<label>/]"):
+            continue
+
+        if line in datatype_bases:
+            datatype_bases_found += 1
+        else:
+            assert line.startswith(datatype_file_start)
+
+    # In this case events is not defined for all datatypes
+    assert datatype_bases_found < datatype_count
+
 
 def test_define_common_principles(schema_obj):
     """Ensure that define_common_principles returns a string."""