Add docs/scripts/auto-update-toctree.py

Makefile

@@ -10,30 +10,7 @@ docs: clean
 	@echo "Cleaning up generated Markdown Notebook files..."
 	@find examples/vertex-ai/notebooks -name "vertex-notebook.md" -type f -delete
 	@echo "Generating YAML tree structure and appending to _toctree.yml..."
-	@echo "# GENERATED CONTENT DO NOT EDIT!" >> docs/source/_toctree.yml
-	@echo "- sections:" >> docs/source/_toctree.yml
-	@for dir in vertex-ai gke cloud-run; do \
-		echo "    - sections:" >> docs/source/_toctree.yml; \
-		find docs/source/examples -name "$$dir-*.mdx" ! -name "$$dir-index.mdx" | sort | while read file; do \
-			base=$$(basename "$$file" .mdx); \
-			title=$$(head -n1 "$$file" | sed 's/^# *//'); \
-			echo "        - local: examples/$$base" >> docs/source/_toctree.yml; \
-			echo "          title: \"$$title\"" >> docs/source/_toctree.yml; \
-		done; \
-		echo "      isExpanded: false" >> docs/source/_toctree.yml; \
-		if [ "$$dir" = "cloud-run" ]; then \
-			echo "      local: examples/$$dir-index" >> docs/source/_toctree.yml; \
-			echo "      title: Cloud Run" >> docs/source/_toctree.yml; \
-		elif [ "$$dir" = "vertex-ai" ]; then \
-			echo "      title: Vertex AI" >> docs/source/_toctree.yml; \
-		else \
-			echo "      local: examples/$$dir-index" >> docs/source/_toctree.yml; \
-			echo "      title: $$(echo $$dir | tr '[:lower:]' '[:upper:]')" >> docs/source/_toctree.yml; \
-		fi; \
-	done
-	@echo "  # local: examples/index" >> docs/source/_toctree.yml
-	@echo "  title: Examples" >> docs/source/_toctree.yml
-	@echo "# END GENERATED CONTENT" >> docs/source/_toctree.yml
+	@python docs/scripts/auto-update-toctree.py
 	@echo "YAML tree structure appended to docs/source/_toctree.yml"
 	@echo "Documentation setup complete."
 

docs/scripts/auto-update-toctree.py

@@ -0,0 +1,79 @@
+import glob
+import re
+
+from pathlib import Path
+
+
+def update_toctree_yaml():
+    output_file = "docs/source/_toctree.yml"
+    dirs = ["vertex-ai", "gke", "cloud-run"]
+
+    with open(output_file, "a") as f:
+        f.write("# GENERATED CONTENT DO NOT EDIT!\n")
+        f.write("- sections:\n")
+
+        for dir in dirs:
+            f.write("    - sections:\n")
+
+            # Find and sort files
+            files = sorted(glob.glob(f"docs/source/examples/{dir}-*.mdx"))
+            files = [file for file in files if not file.endswith(f"{dir}-index.mdx")]
+
+            # Dictionary to store files by type
+            files_by_type = {}
+
+            for file in files:
+                with open(file, "r") as mdx_file:
+                    content = mdx_file.read()
+                    # Extract the metadata surrounded with `---`
+                    metadata = re.search(r"---(.*?)---", content, re.DOTALL)
+                    if metadata:
+                        metadata = metadata.group(1)
+                        metadata = dict(
+                            line.split(": ", 1) for line in metadata.strip().split("\n")
+                        )
+                    else:
+                        metadata = {}
+
+                if not all(key in metadata for key in ["title", "type"]):
+                    print(f"WARNING: Metadata missing in {file}")
+                    print("Ensure that the file contains the following metadata:")
+                    print("title: <title>")
+                    print("type: <type>")
+                    continue
+
+                file_type = metadata["type"]
+                if file_type not in files_by_type:
+                    files_by_type[file_type] = []
+                files_by_type[file_type].append((file, metadata))
+
+            for file_type, file_list in files_by_type.items():
+                f.write("        - sections:\n")
+                for file, metadata in file_list:
+                    base = Path(file).stem
+                    title = metadata["title"]
+                    f.write(f"            - local: examples/{base}\n")
+                    f.write(f'              title: "{title}"\n')
+                f.write("          isExpanded: false\n")
+                f.write(f"          title: {file_type.capitalize()}\n")
+
+            f.write("      isExpanded: false\n")
+
+            if dir == "cloud-run":
+                f.write(f"      local: examples/{dir}-index\n")
+                f.write("      title: Cloud Run\n")
+            elif dir == "vertex-ai":
+                f.write("      title: Vertex AI\n")
+            else:
+                f.write(f"      local: examples/{dir}-index\n")
+                f.write(f"      title: {dir.upper()}\n")
+
+        f.write("  # local: examples/index\n")
+        f.write("  title: Examples\n")
+        f.write("# END GENERATED CONTENT\n")
+
+    print("YAML tree structure appended to docs/source/_toctree.yml")
+
+
+if __name__ == "__main__":
+    update_toctree_yaml()