[SCHEMA] Use mkdocs-gen-files to generate the glossary

.gitignore

@@ -2,6 +2,8 @@ site/
 .DS_Store
 .idea
 venvs
+src/99-appendices/14-glossary.md
+src/99-appendices/14-glossary.html
 .vscode/
 
 pdf_build_src/bids-spec.pdf

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'

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/

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")

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_subobject_table, "MACROS___make_subobject_table")

tools/schemacode/bidsschematools/render.py

@@ -150,11 +150,14 @@ def make_glossary(schema, src_path=None):
 
         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