Adds the ability to include single files as documentation (closes #303).

Author: simonbrowndotje

changelog.md

@@ -4,6 +4,7 @@
 
 - structurizr-dsl: Adds support for element/relationship property expressions (https://github.com/structurizr/java/issues/297).
 - structurizr-dsl: Adds a way to specify the implied relationships strategy by a fully qualified class name via `!impliedRelationships`.
+- structurizr-dsl: Adds the ability to include single files as documentation (https://github.com/structurizr/java/issues/303). 
 
 ## 2.1.4 (18th June 2024)
 

structurizr-dsl/src/main/java/com/structurizr/dsl/DocsParser.java

@@ -55,17 +55,13 @@ private void parse(DslContext context, Documentable documentable, File dslFile,
                 throw new RuntimeException("Documentation path " + path + " does not exist");
             }
 
-            if (!path.isDirectory()) {
-                throw new RuntimeException("Documentation path " + path + " is not a directory");
-            }
-
             try {
                 Class documentationImporterClass = context.loadClass(fullyQualifiedClassName, dslFile);
                 Constructor constructor = documentationImporterClass.getDeclaredConstructor();
                 DocumentationImporter documentationImporter = (DocumentationImporter)constructor.newInstance();
                 documentationImporter.importDocumentation(documentable, path);
 
-                if (!tokens.includes(FQN_INDEX)) {
+                if (!tokens.includes(FQN_INDEX) && path.isDirectory()) {
                     DefaultImageImporter imageImporter = new DefaultImageImporter();
                     imageImporter.importDocumentation(documentable, path);
                 }

structurizr-dsl/src/test/java/com/structurizr/dsl/DslTests.java

@@ -1,6 +1,7 @@
 package com.structurizr.dsl;
 
 import com.structurizr.Workspace;
+import com.structurizr.documentation.Section;
 import com.structurizr.model.*;
 import com.structurizr.view.*;
 import org.junit.jupiter.api.Test;
@@ -12,6 +13,7 @@
 import java.nio.file.Files;
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.Collection;
 import java.util.List;
 
 import static org.junit.jupiter.api.Assertions.*;
@@ -692,9 +694,34 @@ void test_docs() throws Exception {
         Container container = softwareSystem.getContainerWithName("Container");
         Component component = container.getComponentWithName("Component");
 
-        assertEquals(1, parser.getWorkspace().getDocumentation().getSections().size());
-        assertEquals(1, softwareSystem.getDocumentation().getSections().size());
-        assertEquals(1, container.getDocumentation().getSections().size());
+        Collection<Section> sections = parser.getWorkspace().getDocumentation().getSections();
+        assertEquals(1, sections.size());
+        assertEquals("""
+            ## Workspace
+            
+            Content...""", sections.iterator().next().getContent());
+
+        sections = softwareSystem.getDocumentation().getSections();
+        assertEquals(1, sections.size());
+        assertEquals("""
+            ## Software System
+                           
+            Content...""", sections.iterator().next().getContent());
+
+        sections = container.getDocumentation().getSections();
+        assertEquals(1, sections.size());
+        assertEquals("""
+            ## Container
+                           
+            Content...""", sections.iterator().next().getContent());
+
+        sections = component.getDocumentation().getSections();
+        assertEquals(1, sections.size());
+        assertEquals("""
+            ## Component
+                           
+            Content...""", sections.iterator().next().getContent());
+
         assertEquals(1, component.getDocumentation().getSections().size());
     }
 

structurizr-dsl/src/test/resources/dsl/docs/docs/01-context.md

@@ -0,0 +1,3 @@
+## Software System
+
+Content...

structurizr-dsl/src/test/resources/dsl/docs/docs/softwaresystem/1.md

@@ -0,0 +1,3 @@
+## Container
+
+Content...

structurizr-dsl/src/test/resources/dsl/docs/docs/softwaresystem/container/1.md

@@ -0,0 +1,3 @@
+## Component
+
+Content...

structurizr-dsl/src/test/resources/dsl/docs/docs/softwaresystem/container/component/1.md

@@ -0,0 +1,3 @@
+## Workspace
+
+Content...

structurizr-dsl/src/test/resources/dsl/docs/docs/workspace/1.md

@@ -1,17 +1,17 @@
 workspace {
 
-    !docs docs com.structurizr.example.ExampleDocumentationImporter
+    !docs docs/workspace com.structurizr.example.ExampleDocumentationImporter
 
     model {
         user = person "User"
         softwareSystem = softwareSystem "Software System" {
-            !docs docs
+            !docs docs/softwaresystem
 
             container "Container" {
-                !docs docs
+                !docs docs/softwaresystem/container
 
                 component "Component" {
-                    !docs docs
+                    !docs docs/softwaresystem/container/component/1.md
                 }
             }
         }