Add graph legend (#1363)

Adds a legend explaining the color of the nodes in the agda-unimath
dependency graph introduced in #1348.

Author: fredrik-bakke

.gitignore

@@ -431,3 +431,4 @@ CONTRIBUTORS.md
 MAINTAINERS.md
 /website/css/Agda-highlight.css
 /website/images/agda_dependency_graph.svg
+/website/images/agda_dependency_graph_legend.html

ART.md

@@ -2,8 +2,13 @@
 
 <div align="center" style="margin: 2em 0;">
   <figure>
-    <img src="website/images/agda_dependency_graph.svg" alt="A dependency graph of the library, color coded by field. Fredrik Bakke. 2025 - perpetuity" width="95%" style="border-radius: 10px;">
-    <figcaption>A dependency graph of the library, color coded by field. Fredrik Bakke. 2025 - perpetuity</figcaption>
+    <img src="website/images/agda_dependency_graph.svg" alt="A dependency graph of the library, color coded by namespace. Fredrik Bakke. 2025 — perpetuity" width="95%" style="border-radius: 10px;">
+    <br>
+    <span>
+    {{#include website/images/agda_dependency_graph_legend.html}}
+    </span>
+    <figcaption>A dependency graph of the library, color coded by namespace. Fredrik Bakke. 2025 — perpetuity</figcaption>
+
   </figure>
 </div>
 

Makefile

@@ -145,12 +145,13 @@ CONTRIBUTORS.md: ${AGDAFILES} ${CONTRIBUTORS_FILE} ./scripts/generate_contributo
 website/css/Agda-highlight.css: ./scripts/generate_agda_css.py ./theme/catppuccin.css
 	@python3 ./scripts/generate_agda_css.py
 
-website/images/agda_dependency_graph.svg: ${AGDAFILES}
+website/images/agda_dependency_graph.svg website/images/agda_dependency_graph_legend.html &: ${AGDAFILES}
 	@python3 ./scripts/generate_dependency_graph_rendering.py website/images/agda_dependency_graph svg || true
 
 .PHONY: website-prepare
 website-prepare: agda-html ./SUMMARY.md ./CONTRIBUTORS.md ./MAINTAINERS.md \
-								 ./website/css/Agda-highlight.css ./website/images/agda_dependency_graph.svg
+								 ./website/css/Agda-highlight.css ./website/images/agda_dependency_graph.svg \
+								 ./website/images/agda_dependency_graph_legend.html
 	@cp $(METAFILES) ./docs/
 	@mkdir -p ./docs/website
 	@cp -r ./website/images ./docs/website/

scripts/generate_dependency_graph_rendering.py

@@ -133,6 +133,17 @@ def build_dependency_graph(root_dir, most_imported_drop_count=20):
 
     return graph, file_sizes
 
+def generate_html_legend(label_colors, used_labels, output_file, label_counts):
+    """Generate an HTML legend with used namespaces and their colors."""
+    sorted_labels = sorted(used_labels, key=lambda label: label_counts.get(label, 0), reverse=True)
+    with open(output_file, 'w') as f:
+        f.write('<div class="art-fredrik-dependency-graph-legend">\n')
+        for label in sorted_labels:
+            if label in label_colors:
+                color = label_colors[label]
+                f.write(f'  <pre class="art-fredrik-dependency-graph-label" id="{label}"><span class="art-fredrik-dependency-graph-dot" style="background-color: #{color};"></span>{label}</pre>\n')
+        f.write('</div>\n')
+
 def render_graph(graph, file_sizes, output_file, format, repo):
     """Render the dependency graph using Graphviz."""
     # Fetch GitHub labels and colors
@@ -147,14 +158,25 @@ def render_graph(graph, file_sizes, output_file, format, repo):
     node_sizes = {node: max(0.05, 0.3 * math.sqrt(file_sizes.get(node, 0) / max_lines)) for node in graph}
     node_colors = {node: module_based_color(node[:node.rfind(".")], label_colors) for node in graph}
 
+    used_labels = set()
+    label_counts = defaultdict(int)
+
     for node, dependencies in graph.items():
         node_color = node_colors[node]
+        label = node[:node.rfind(".")]
+        used_labels.add(label)
+        label_counts[label] += 1
         dot.node(node, shape="circle", style="filled", fillcolor=node_color, color="#FFFFFF00", width=str(node_sizes[node]), height=str(node_sizes[node]), label="")
         for dep in dependencies:
             if dep in graph:  # Ensure we're not linking to removed nodes
                 edge_color =  node_color + "10"
                 dot.edge(node, dep, color=edge_color, arrowhead="none")
 
+    # Generate HTML legend
+    html_legend_output_file = output_file + "_legend.html"
+    generate_html_legend(label_colors, used_labels, html_legend_output_file, label_counts)
+    eprint(f"HTML Legend saved as {html_legend_output_file}")
+
     dot.render(output_file, format=format, cleanup=True)
 
 if __name__ == "__main__":

theme/css/general.css

@@ -252,3 +252,27 @@ kbd {
 span.prefer-nobreak {
   display: inline-block;
 }
+
+.art-fredrik-dependency-graph-legend {
+  line-height: 1;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.art-fredrik-dependency-graph-dot {
+  height: 10px;
+  width: 10px;
+  border-radius: 50%;
+  display: inline-block;
+  margin-right: 2.5px;
+  margin-left: 4px;
+}
+
+.art-fredrik-dependency-graph-label {
+  white-space: nowrap;
+  font-size: 50%;
+  display: inline-block;
+  margin: 0;
+  padding: 0.1rem 0.3rem;
+}