From c23697aaa7edbefce73744e3e484e303b4d34061 Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Fri, 11 Oct 2024 23:51:32 +0200
Subject: [PATCH] Use method colour key in the Builder API graph (#12998)

---
 doc/_static/diagrams/sphinx_build_flow.dot | 43 +++++++++++++++++++---
 doc/extdev/builderapi.rst                  |  2 +-
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/doc/_static/diagrams/sphinx_build_flow.dot b/doc/_static/diagrams/sphinx_build_flow.dot
index 59fbdd0d1..702272fcb 100644
--- a/doc/_static/diagrams/sphinx_build_flow.dot
+++ b/doc/_static/diagrams/sphinx_build_flow.dot
@@ -13,26 +13,54 @@ digraph build {
         shape=record
         label = "Sphinx | <init> __init__ | <build> build"
     ];
+    "legend" [
+        shape=record
+        label = <<table border="0" cellborder="0" cellspacing="0">
+            <tr><td align="center"><u><b>Method types</b></u></td></tr>
+            <tr><td align="left"><font color="darkorange">Final</font></td></tr>
+            <tr><td align="left"><font color="darkblue">Overridable</font></td></tr>
+            <tr><td align="left"><font color="darkgreen">Abstract</font></td></tr>
+        </table>>
+    ];
+    {rank=same; "Sphinx" "legend" };
+
+    "Builder.init" [color=darkblue];
+    "Builder.build_all" [color=darkorange];
+    "Builder.build_specific" [color=darkorange];
+    "Builder.build_update" [color=darkorange];
+
     "Sphinx":init -> "Builder.init";
     "Sphinx":build -> "Builder.build_all";
     "Sphinx":build -> "Builder.build_specific";
-    "Builder.build_update" [
-        shape=record
-        label = "<p1> Builder.build_update | Builder.get_outdated_docs"
-    ];
-    "Sphinx":build -> "Builder.build_update":p1 ;
+    "Sphinx":build -> "Builder.build_update";
+
+    "Builder.get_outdated_docs" [color=darkgreen];
+    "Builder.build_update" -> "Builder.get_outdated_docs";
+
+    "Builder.build" [color=darkorange];
 
     "Builder.build_all" -> "Builder.build";
     "Builder.build_specific" -> "Builder.build";
     "Builder.build_update":p1 -> "Builder.build";
 
+    "Builder.read" [color=darkorange];
+    "Builder.write" [color=darkorange];
+    "Builder.finish" [color=darkblue];
+
     "Builder.build" -> "Builder.read";
     "Builder.build" -> "Builder.write";
     "Builder.build" -> "Builder.finish";
 
+    "Builder.read_doc" [color=darkorange];
+    "Builder.write_doctree" [color=darkorange];
+
     "Builder.read" -> "Builder.read_doc";
     "Builder.read_doc" -> "Builder.write_doctree";
 
+    "Builder.prepare_writing" [color=darkblue];
+    "Builder.copy_assets" [color=darkblue];
+    "Builder.write_documents" [color=darkblue];
+
     "Builder.write":p1 -> "Builder.prepare_writing";
     "Builder.write":p1 -> "Builder.copy_assets";
     "Builder.write_documents" [
@@ -41,8 +69,13 @@ digraph build {
     ];
     "Builder.write":p1 -> "Builder.write_documents";
 
+    "Builder.write_doc" [color=darkgreen];
+    "Builder.get_relative_uri" [color=darkblue];
+
     "Builder.write_documents":p1 -> "Builder.write_doc";
     "Builder.write_doc" -> "Builder.get_relative_uri";
 
+    "Builder.get_target_uri" [color=darkgreen];
+
     "Builder.get_relative_uri" -> "Builder.get_target_uri";
 }
diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
index ccc0da8c5..6e60acad8 100644
--- a/doc/extdev/builderapi.rst
+++ b/doc/extdev/builderapi.rst
@@ -12,7 +12,7 @@ Builder API
    It follows this basic workflow:
 
    .. graphviz:: /_static/diagrams/sphinx_build_flow.dot
-      :caption: UML for the standard Sphinx build workflow
+      :caption: Call graph for the standard Sphinx build workflow
 
    .. rubric:: Overridable Attributes