From 61dfa960e1ecbba74fdda1460f9109a65cd79312 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 24 Mar 2022 17:35:49 -0400
Subject: [PATCH 1/2] Use mkdocs-gen-files to generate the glossary.

---
 .gitignore                         |  2 ++
 mkdocs.yml                         |  3 +++
 requirements.txt                   |  1 +
 src/99-appendices/14-glossary.md   |  9 ---------
 tools/generate_glossary.py         | 24 ++++++++++++++++++++++++
 tools/mkdocs_macros_bids/macros.py | 15 ---------------
 tools/mkdocs_macros_bids/main.py   |  1 -
 7 files changed, 30 insertions(+), 25 deletions(-)
 delete mode 100644 src/99-appendices/14-glossary.md
 create mode 100644 tools/generate_glossary.py

diff --git a/.gitignore b/.gitignore
index 6e97a859ac..cc822bef50 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,8 @@ site/
 .DS_Store
 .idea
 venvs
+src/99-appendices/14-glossary.md
+src/99-appendices/14-glossary.html
 
 pdf_build_src/bids-spec.pdf
 pdf_build_src/bids-spec_pandoc_log.json
diff --git a/mkdocs.yml b/mkdocs.yml
index 01eb96dd5c..e5eeb82c42 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -29,6 +29,9 @@ plugins:
          - branch: /(?!^master$)/
            +extra_css:
              - css/watermark.css
+    - gen-files:
+        scripts:
+          - tools/generate_glossary.py
     - macros:
         module_name: tools/mkdocs_macros_bids/main
 docs_dir: 'src'
diff --git a/requirements.txt b/requirements.txt
index edc1538e9f..a65f629c4b 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -2,6 +2,7 @@ mkdocs>=1.1
 mkdocs-material>=5.4
 pymdown-extensions>=7.0.0
 mkdocs-branchcustomization-plugin~=0.1.3
+mkdocs-gen-files
 mkdocs-macros-plugin
 numpy
 tools/schemacode/
diff --git a/src/99-appendices/14-glossary.md b/src/99-appendices/14-glossary.md
deleted file mode 100644
index 8f9affb6f1..0000000000
--- a/src/99-appendices/14-glossary.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Appendix XIV: Glossary of schema objects
-
-This section compiles the object definitions in the schema.
-
-<!--
-  This section is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY.
-  Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#updating-the-schema
--->
-{{ MACROS___make_glossary() }}
diff --git a/tools/generate_glossary.py b/tools/generate_glossary.py
new file mode 100644
index 0000000000..eb5f574e79
--- /dev/null
+++ b/tools/generate_glossary.py
@@ -0,0 +1,24 @@
+"""Generate the Glossary appendix file."""
+import os.path as op
+
+import mkdocs_gen_files
+
+from schemacode import render, schema, utils
+
+out_file = op.abspath("src/99-appendices/14-glossary.md")
+
+output = """# Appendix XIV: Glossary of schema objects
+
+This section compiles the object definitions in the schema.
+
+"""
+
+schemapath = utils.get_schema_path()
+schema_obj = schema.load_schema(schemapath)
+text = render.make_glossary(schema_obj)
+output += text
+
+with mkdocs_gen_files.open(out_file, "w") as fobj:
+    fobj.write(output)
+
+mkdocs_gen_files.set_edit_path(out_file, "tools/generate_glossary.py")
diff --git a/tools/mkdocs_macros_bids/macros.py b/tools/mkdocs_macros_bids/macros.py
index 6f4363fbff..963149da0a 100644
--- a/tools/mkdocs_macros_bids/macros.py
+++ b/tools/mkdocs_macros_bids/macros.py
@@ -71,21 +71,6 @@ def make_entity_definitions():
     return text
 
 
-def make_glossary():
-    """Generate glossary.
-
-    Returns
-    -------
-    text : str
-        A multiline string containing descriptions and some formatting
-        information about the entities in the schema.
-    """
-    schemapath = utils.get_schema_path()
-    schema_obj = schema.load_schema(schemapath)
-    text = render.make_glossary(schema_obj)
-    return text
-
-
 def make_suffix_table(suffixes):
     """Generate a markdown table of suffix information.
 
diff --git a/tools/mkdocs_macros_bids/main.py b/tools/mkdocs_macros_bids/main.py
index 56c1d725ed..8db94a0411 100644
--- a/tools/mkdocs_macros_bids/main.py
+++ b/tools/mkdocs_macros_bids/main.py
@@ -35,7 +35,6 @@ def define_env(env):
         macros.make_entity_definitions,
         "MACROS___make_entity_definitions",
     )
-    env.macro(macros.make_glossary, "MACROS___make_glossary")
     env.macro(macros.make_suffix_table, "MACROS___make_suffix_table")
     env.macro(macros.make_metadata_table, "MACROS___make_metadata_table")
     env.macro(macros.make_columns_table, "MACROS___make_columns_table")

From 6dbf8ae03fafb1998859ca084d28d507acf28dcb Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 31 Mar 2022 14:48:05 -0400
Subject: [PATCH 2/2] Improve the glossary format.

---
 tools/schemacode/schemacode/render.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/tools/schemacode/schemacode/render.py b/tools/schemacode/schemacode/render.py
index ea4f0fd1f9..c3de94a942 100644
--- a/tools/schemacode/schemacode/render.py
+++ b/tools/schemacode/schemacode/render.py
@@ -122,11 +122,14 @@ def make_glossary(schema):
 
         text += f'\n<a name="{obj_marker}"></a>'
         text += f"\n## {obj_key}\n\n"
-        text += f"name: {obj_name}\n\n"
-        text += f"description:\n>{obj_desc}\n\n"
+        text += f"**Name**: {obj_name}\n\n"
+        text += f"**Description**:\n\t{obj_desc}\n\n"
 
         temp_obj_def = {k: v for k, v in obj_def.items() if k not in ("description", "name")}
-        text += f"schema information:\n```yaml\n{temp_obj_def}\n```"
+        if temp_obj_def:
+            from pprint import pformat
+            temp_obj_def_str = pformat(temp_obj_def)
+            text += f"**Additional schema information**:\n```yaml\n{temp_obj_def_str}\n```"
 
     return text