Some updates to the architecture documentation (#28171)

architecture/README.md

@@ -0,0 +1,60 @@
+<!-- 
+  -- Note: this file contains a generated diagram. Use `./gradlew :architectureDoc` to generate 
+  -->
+
+# Gradle platform architecture
+
+The diagram below shows the main components of the Gradle architecture. See [ADR4](standards/0004-use-a-platform-architecture.md) for more details.
+
+<!-- This diagram is generated. Use `./gradlew :architectureDoc` to update it -->
+```mermaid
+    graph TD
+
+    subgraph core["core platform"]
+
+        core_runtime["core-runtime module"]
+        style core_runtime stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+
+        core_configuration["core-configuration module"]
+        style core_configuration stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+
+        core_execution["core-execution module"]
+        style core_execution stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+    end
+    style core fill:#c2e0f4,stroke:#3498db,stroke-width:2px;
+
+    documentation["documentation module"]
+    style documentation stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+
+    ide["ide module"]
+    style ide stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+
+    subgraph software["software platform"]
+    end
+    style software fill:#c2e0f4,stroke:#3498db,stroke-width:2px;
+    software --> core
+
+    subgraph jvm["jvm platform"]
+    end
+    style jvm fill:#c2e0f4,stroke:#3498db,stroke-width:2px;
+    jvm --> core
+    jvm --> software
+
+    subgraph extensibility["extensibility platform"]
+    end
+    style extensibility fill:#c2e0f4,stroke:#3498db,stroke-width:2px;
+    extensibility --> core
+    extensibility --> jvm
+
+    subgraph native["native platform"]
+    end
+    style native fill:#c2e0f4,stroke:#3498db,stroke-width:2px;
+    native --> core
+    native --> software
+
+    enterprise["enterprise module"]
+    style enterprise stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+
+    build_infrastructure["build-infrastructure module"]
+    style build_infrastructure stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
+```

settings.gradle.kts

@@ -290,12 +290,16 @@ gradle.settingsEvaluated {
 gradle.rootProject {
     tasks.register("architectureDoc", GeneratorTask::class.java) {
         description = "Generates the architecture documentation"
-        outputFile = layout.projectDirectory.file("architecture/readme.md")
+        outputFile = layout.projectDirectory.file("architecture/README.md")
         elements = provider { architectureElements.map { it.build() } }
     }
 }
 
 abstract class GeneratorTask : DefaultTask() {
+    private val markerComment = "<!-- This diagram is generated. Use `./gradlew :architectureDoc` to update it -->"
+    private val startDiagram = "```mermaid"
+    private val endDiagram = "```"
+
     @get:OutputFile
     abstract val outputFile: RegularFileProperty
 
@@ -304,14 +308,23 @@ abstract class GeneratorTask : DefaultTask() {
 
     @TaskAction
     fun generate() {
-        outputFile.asFile.get().bufferedWriter().use {
+        val markdownFile = outputFile.asFile.get()
+        val content = markdownFile.readText().lines()
+        val markerPos = content.indexOfFirst { it.contains(markerComment) }
+        if (markerPos < 0) {
+            throw IllegalArgumentException("Could not locate the generated diagram in $markdownFile")
+        }
+        val endPos = content.subList(markerPos, content.size).indexOfFirst { it.contains(endDiagram) && !it.contains(startDiagram) }
+        if (endPos < 0) {
+            throw IllegalArgumentException("Could not locate the end of the generated diagram in $markdownFile")
+        }
+        val head = content.subList(0, markerPos)
+
+        markdownFile.bufferedWriter().use {
             PrintWriter(it).run {
-                println(
-                    """
-                    <!-- This is a generated file. Use `./gradlew :architectureDoc` to generate -->
-                    # Gradle platform architecture
-                """.trimIndent()
-                )
+                for (line in head) {
+                    println(line)
+                }
                 graph(elements.get())
             }
         }
@@ -320,41 +333,57 @@ abstract class GeneratorTask : DefaultTask() {
     private fun PrintWriter.graph(elements: List<ArchitectureElement>) {
         println(
             """
-            ```mermaid
-                graph TD
+            $markerComment
+            $startDiagram
         """.trimIndent()
         )
+        val writer = NodeWriter(this, "    ")
+        writer.node("graph TD")
         for (element in elements) {
             if (element is Platform) {
-                platform(element)
+                writer.platform(element)
             } else {
-                element(element)
+                writer.element(element)
             }
         }
-        println("```")
+        println(endDiagram)
     }
 
-    private fun PrintWriter.platform(platform: Platform) {
+    private fun NodeWriter.platform(platform: Platform) {
         println()
-        println("subgraph ${platform.id}[\"${platform.name} platform\"]")
-        for (child in platform.children) {
-            element(child)
+        node("subgraph ${platform.id}[\"${platform.name} platform\"]") {
+            for (child in platform.children) {
+                element(child)
+            }
         }
-        println("end")
-        println("style ${platform.id} fill:#c2e0f4,stroke:#3498db,stroke-width:2px;")
+        node("end")
+        node("style ${platform.id} fill:#c2e0f4,stroke:#3498db,stroke-width:2px;")
         for (dep in platform.uses) {
-            println("${platform.id} --> $dep")
+            node("${platform.id} --> $dep")
         }
     }
 
-    private fun PrintWriter.element(element: ArchitectureElement) {
+    private fun NodeWriter.element(element: ArchitectureElement) {
         println()
-        println(
-            """
-            ${element.id}["${element.name} module"]
-            style ${element.id} stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;
-        """.trimIndent()
-        )
+        node("${element.id}[\"${element.name} module\"]")
+        node("style ${element.id} stroke:#1abc9c,fill:#b1f4e7,stroke-width:2px;")
+    }
+
+    private class NodeWriter(private val writer: PrintWriter, private val indent: String) {
+        fun println() {
+            writer.println()
+        }
+
+        fun node(node: String) {
+            writer.print(indent)
+            writer.println(node)
+        }
+
+        fun node(node: String, builder: NodeWriter.() -> Unit) {
+            writer.print(indent)
+            writer.println(node)
+            builder(NodeWriter(writer, "$indent    "))
+        }
     }
 }
 
@@ -392,7 +421,7 @@ class ProjectScope(
     }
 }
 
-class ElementId(val id: String): Serializable {
+class ElementId(val id: String) : Serializable {
     override fun toString(): String {
         return id
     }