From e3fb8eced29a1f92c269b6f9b6f7c94ad301e911 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 29 Aug 2022 19:21:21 +0200
Subject: [PATCH 1/5] add legend below filename template

---
 tools/schemacode/bidsschematools/render.py | 44 ++++++++++++++++++++++
 tools/schemacode/setup.cfg                 |  1 +
 2 files changed, 45 insertions(+)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 7af32cc3dc..65aa4f1d39 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -7,6 +7,7 @@
 
 import pandas as pd
 import yaml
+from markdown_it import MarkdownIt
 from tabulate import tabulate
 
 from . import utils
@@ -469,11 +470,54 @@ def make_filename_template(
         )
 
     codeblock = codeblock.expandtabs(4)
+    codeblock = append_filename_template_legend(codeblock, pdf_format)
     codeblock = codeblock.replace("SPEC_ROOT", get_relpath(src_path))
 
     return codeblock
 
 
+def append_filename_template_legend(
+    text=None,
+    pdf_format=False,
+):
+
+    if text is None:
+        return
+
+    md = MarkdownIt().disable("image").enable("table")
+
+    legend = """
+- Filename entities or folders between square brackets (for example, `[_ses-<label>]`) are OPTIONAL.
+- Some entities may only allow specific values,
+  in which case those values are listed in `<>`, separated by `|`.
+- `_<suffix>` means that there are several (>6) valid suffixes for this filename pattern.
+- `.<extension>` means that there are several (>6) valid extensions for this file type.
+- `[.gz]` means that both the unzipped and gzipped versions of the extension are valid.
+"""
+
+    if pdf_format:
+        text += f"""
+
+**Legend**:
+
+{legend}
+
+"""
+    else:
+        text += f"""
+
+<details>
+<summary><strong>Legend:</strong></summary>
+<ul>
+{md.render(legend)}
+</ul>
+</details>
+
+"""
+
+    return text
+
+
 def make_entity_table(schema, tablefmt="github", **kwargs):
     """Produce entity table (markdown) based on schema.
 
diff --git a/tools/schemacode/setup.cfg b/tools/schemacode/setup.cfg
index eb55393ddd..5968790370 100644
--- a/tools/schemacode/setup.cfg
+++ b/tools/schemacode/setup.cfg
@@ -34,6 +34,7 @@ doc =
 render =
     tabulate
     pandas
+    markdown-it-py
 tests =
     codecov
     coverage[toml]

From c001c1232e00a877b00f469e1aef5d69cd751576 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 29 Aug 2022 19:25:50 +0200
Subject: [PATCH 2/5] lint

---
 tools/schemacode/bidsschematools/render.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 65aa4f1d39..932add5dd8 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -487,7 +487,8 @@ def append_filename_template_legend(
     md = MarkdownIt().disable("image").enable("table")
 
     legend = """
-- Filename entities or folders between square brackets (for example, `[_ses-<label>]`) are OPTIONAL.
+- Filename entities or folders between square brackets 
+  (for example, `[_ses-<label>]`) are OPTIONAL.
 - Some entities may only allow specific values,
   in which case those values are listed in `<>`, separated by `|`.
 - `_<suffix>` means that there are several (>6) valid suffixes for this filename pattern.

From b16ff59c98b3d2abf1c2b7199b7b390edb04899c Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Mon, 29 Aug 2022 19:27:09 +0200
Subject: [PATCH 3/5] lint

---
 tools/schemacode/bidsschematools/render.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 932add5dd8..9e50a48136 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -487,7 +487,7 @@ def append_filename_template_legend(
     md = MarkdownIt().disable("image").enable("table")
 
     legend = """
-- Filename entities or folders between square brackets 
+- Filename entities or folders between square brackets
   (for example, `[_ses-<label>]`) are OPTIONAL.
 - Some entities may only allow specific values,
   in which case those values are listed in `<>`, separated by `|`.

From 889e6a166791df29f8fa602a05fb5c6e4937308a Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Tue, 30 Aug 2022 09:57:53 +0200
Subject: [PATCH 4/5] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 tools/schemacode/bidsschematools/render.py | 14 ++------------
 1 file changed, 2 insertions(+), 12 deletions(-)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 9e50a48136..33b8929175 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -476,14 +476,7 @@ def make_filename_template(
     return codeblock
 
 
-def append_filename_template_legend(
-    text=None,
-    pdf_format=False,
-):
-
-    if text is None:
-        return
-
+def append_filename_template_legend(text, pdf_format=False):
     md = MarkdownIt().disable("image").enable("table")
 
     legend = """
@@ -505,15 +498,12 @@ def append_filename_template_legend(
 
 """
     else:
+        md = MarkdownIt()
         text += f"""
-
 <details>
 <summary><strong>Legend:</strong></summary>
-<ul>
 {md.render(legend)}
-</ul>
 </details>
-
 """
 
     return text

From 649e4e41ec68d0078487dbc64d9e2a6c6630f5d7 Mon Sep 17 00:00:00 2001
From: Remi Gau <remi_gau@hotmail.com>
Date: Tue, 30 Aug 2022 09:58:46 +0200
Subject: [PATCH 5/5] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 tools/schemacode/bidsschematools/render.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tools/schemacode/bidsschematools/render.py b/tools/schemacode/bidsschematools/render.py
index 33b8929175..1ee8e7cb95 100644
--- a/tools/schemacode/bidsschematools/render.py
+++ b/tools/schemacode/bidsschematools/render.py
@@ -477,8 +477,6 @@ def make_filename_template(
 
 
 def append_filename_template_legend(text, pdf_format=False):
-    md = MarkdownIt().disable("image").enable("table")
-
     legend = """
 - Filename entities or folders between square brackets
   (for example, `[_ses-<label>]`) are OPTIONAL.