feat: build YAML table of contents for examples

Author: gvwilson

Makefile

@@ -35,6 +35,10 @@ examples-force:
 	touch ${EXAMPLES_SRC}
 	make examples
 
+## examples-toc: generate YAML table of contents for examples
+examples-toc:
+	@python bin/build_example_toc.py ${EXAMPLE_SRC}
+
 ## format: reformat code
 format:
 	${RUN} ruff format ${CODE_DIRS}

bin/build_example_toc.py

@@ -0,0 +1,36 @@
+from collections import defaultdict
+from pathlib import Path
+import sys
+import yaml
+
+
+SKIPS = {"getting-started.md"}
+
+
+def main():
+    """Main driver."""
+    sources = [Path(a) for a in sys.argv[1:]]
+    sources = [src for src in sources if str(src.name) not in SKIPS]
+
+    sections = defaultdict(list)
+    for src in sources:
+        try:
+            content = src.read_text()
+            header = content.split("---")[1].strip()
+            data = yaml.safe_load(header)
+            data = data["jupyter"]["plotly"]
+            display = data["display_as"]
+            order = float(data["order"])
+            sections[display].append((order, data, src.name))
+        except Exception as exc:
+            print(f"failed to load from {src}: {exc}", file=sys.stderr)
+
+    for key, values in sorted(sections.items()):
+        values.sort(key=lambda x: float(x[0]))
+        print(f"- {key}")
+        for (order, data, src) in values:
+            print(f'  - {src}: "{data["name"]}"')
+
+
+if __name__ == "__main__":
+    main()

bin/check-all-md.py

@@ -56,7 +56,8 @@ dev_build = [
     "mkdocs-material",
     "mkdocstrings[python]",
     "mkdocs-gen-files",
-    "mkdocs-literate-nav"
+    "mkdocs-literate-nav",
+    "pyyaml"
 ]
 dev_optional = [
     "plotly[dev_build]",