Merge pull request #179 from jp7677/section-title

Update structurizr libraries

build.gradle.kts

@@ -19,9 +19,9 @@ dependencies {
 
     implementation("org.eclipse.jgit:org.eclipse.jgit:6.5.0.202303070854-r")
 
-    implementation("com.structurizr:structurizr-core:1.21.0")
-    implementation("com.structurizr:structurizr-dsl:1.27.1")
-    implementation("com.structurizr:structurizr-export:1.10.1")
+    implementation("com.structurizr:structurizr-core:1.23.0")
+    implementation("com.structurizr:structurizr-dsl:1.29.0")
+    implementation("com.structurizr:structurizr-export:1.12.1")
 
     implementation("net.sourceforge.plantuml:plantuml:1.2023.4")
 

docs/example/internet-banking-system/docs/0001-history.md

@@ -1,5 +1,3 @@
-# Documentation
+# History
 
-## History
-
-Some notes how we got to the current state.
+Some notes how we got to the current state.

docs/example/internet-banking-system/docs/0002-guide.md

@@ -1,5 +1,3 @@
-# Documentation
-
-## Usage
+# Usage
 
 This is how we use this thing.

src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/MenuViewModel.kt

@@ -16,7 +16,7 @@ class MenuViewModel(generatorContext: GeneratorContext, private val pageViewMode
         generatorContext.workspace.documentation.sections
             .sortedBy { it.order }
             .drop(1)
-            .forEach { yield(createMenuItem(it.title, WorkspaceDocumentationSectionPageViewModel.url(it))) }
+            .forEach { yield(createMenuItem(it.contentTitle(), WorkspaceDocumentationSectionPageViewModel.url(it))) }
     }.toList()
 
     val softwareSystemItems = generatorContext.workspace.model.includedSoftwareSystems

src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/SectionTitle.kt

@@ -0,0 +1,36 @@
+package nl.avisi.structurizr.site.generatr.site.model
+
+import com.structurizr.documentation.Format
+import com.structurizr.documentation.Section
+import com.vladsch.flexmark.ast.Heading
+import com.vladsch.flexmark.ast.Paragraph
+import com.vladsch.flexmark.parser.Parser
+
+private val parser = Parser.builder().build()
+private const val MAX_TITLE_LENGTH = 50
+
+fun Section.contentTitle(): String {
+    if (format != Format.Markdown)
+        return "unsupported document"
+
+    val document = parser.parse(content)
+
+    if (!document.hasChildren())
+        return "untitled document"
+
+    val header = document.children.firstOrNull { it is Heading }?.let { it as Heading }
+    if (header != null)
+        return header.text.toString()
+
+    val paragraph = document.children.firstOrNull { it is Paragraph }?.let { it as Paragraph }?.chars?.toString()
+    if (paragraph != null)
+        return if (paragraph.length > MAX_TITLE_LENGTH) {
+            val whitespacePosition = paragraph.withIndex()
+                .filter { it.value.isWhitespace() }
+                .lastOrNull { it.index < MAX_TITLE_LENGTH }
+                ?.index
+            paragraph.take(whitespacePosition ?: MAX_TITLE_LENGTH)
+        } else paragraph
+
+    return "unknown document"
+}

src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/SectionsTableViewModel.kt

@@ -12,7 +12,7 @@ fun PageViewModel.createSectionsTableViewModel(sections: Collection<Section>, hr
             .forEach { (section, index) ->
                 bodyRow(
                     cellWithIndex(index.toString()),
-                    cellWithLink(this@createSectionsTableViewModel, section.title, hrefFactory(section))
+                    cellWithLink(this@createSectionsTableViewModel, section.contentTitle(), hrefFactory(section))
                 )
             }
     }

src/main/kotlin/nl/avisi/structurizr/site/generatr/site/model/WorkspaceDocumentationSectionPageViewModel.kt

@@ -7,13 +7,13 @@ import nl.avisi.structurizr.site.generatr.site.GeneratorContext
 class WorkspaceDocumentationSectionPageViewModel(generatorContext: GeneratorContext, section: Section) :
     PageViewModel(generatorContext) {
     override val url = url(section)
-    override val pageSubTitle: String = section.title
+    override val pageSubTitle: String = section.contentTitle()
 
     val content = markdownToHtml(this, section.content, generatorContext.svgFactory)
 
     companion object {
         fun url(section: Section): String {
-            return "/${section.title.normalize()}"
+            return "/${section.contentTitle().normalize()}"
         }
     }
 }

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/HomePageViewModelTest.kt

@@ -3,8 +3,6 @@ package nl.avisi.structurizr.site.generatr.site.model
 import assertk.assertThat
 import assertk.assertions.isEqualTo
 import assertk.assertions.isTrue
-import com.structurizr.documentation.Format
-import com.structurizr.documentation.Section
 import nl.avisi.structurizr.site.generatr.site.model.HomePageViewModel.Companion.DEFAULT_HOMEPAGE_CONTENT
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.ValueSource
@@ -30,7 +28,7 @@ class HomePageViewModelTest : ViewModelTest() {
     fun `homepage with workspace docs`() {
         val generatorContext = generatorContext()
         generatorContext.workspace.documentation.addSection(
-            Section("Section title", Format.Markdown, "Section content")
+            createSection("Section content")
         )
         val viewModel = HomePageViewModel(generatorContext)
 

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/MenuViewModelTest.kt

@@ -7,7 +7,6 @@ import assertk.assertions.isEqualTo
 import assertk.assertions.isTrue
 import com.structurizr.documentation.Decision
 import com.structurizr.documentation.Format
-import com.structurizr.documentation.Section
 import com.structurizr.model.Location
 import nl.avisi.structurizr.site.generatr.site.GeneratorContext
 import org.junit.jupiter.api.Test
@@ -66,10 +65,10 @@ class MenuViewModelTest : ViewModelTest() {
     @ValueSource(strings = ["main", "branch-2"])
     fun `workspace-level documentation in general section`(currentBranch: String) {
         val generatorContext = generatorContext(branches = listOf("main", "branch-2"), currentBranch = currentBranch)
-        generatorContext.workspace.documentation.addSection(Section("Home", Format.Markdown, "content"))
-        val section1 = Section("Doc 1", Format.Markdown, "content")
+        generatorContext.workspace.documentation.addSection(createSection("# Home"))
+        val section1 = createSection("# Doc 1")
             .also { generatorContext.workspace.documentation.addSection(it) }
-        val section2 = Section("Doc Title 2", Format.Markdown, "content")
+        val section2 = createSection(" Doc Title 2")
             .also { generatorContext.workspace.documentation.addSection(it) }
         val pageViewModel = createPageViewModel(generatorContext)
         val viewModel = MenuViewModel(generatorContext, pageViewModel)

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/SectionTitleTest.kt

@@ -0,0 +1,61 @@
+package nl.avisi.structurizr.site.generatr.site.model
+
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import com.structurizr.documentation.Format
+import com.structurizr.documentation.Section
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+
+class SectionTitleTest {
+
+    @Test
+    fun `no content`() {
+        val section = Section(Format.Markdown, "")
+        assertThat(section.contentTitle()).isEqualTo("untitled document")
+    }
+
+    @Test
+    fun `only whitespaces`() {
+        val section = Section(Format.Markdown, " \n ")
+        assertThat(section.contentTitle()).isEqualTo("untitled document")
+    }
+
+    @Test
+    fun `no markdown`() {
+        val section = Section(Format.AsciiDoc, "== title")
+        assertThat(section.contentTitle()).isEqualTo("unsupported document")
+    }
+
+    @Test
+    fun `short paragraph`() {
+        val section = Section(Format.Markdown, "some content")
+        assertThat(section.contentTitle()).isEqualTo("some content")
+    }
+
+    @Test
+    fun `long paragraph`() {
+        val section = Section(
+            Format.Markdown,
+            "some very very long content we really need to truncate since no one wants to read such an exhausting title"
+        )
+        assertThat(section.contentTitle()).isEqualTo("some very very long content we really need to")
+    }
+
+    @Test
+    fun `long paragraph without whitespaces`() {
+        val section = Section(
+            Format.Markdown,
+            "some-very-very-long-content-we-really-need-to-truncate-since-no-one-wants-to-read-such-an-exhausting-title"
+        )
+        assertThat(section.contentTitle()).isEqualTo("some-very-very-long-content-we-really-need-to-trun")
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = ["# header", "## header", "### header"])
+    fun `with heading`(content: String) {
+        val section = Section(Format.Markdown, content)
+        assertThat(section.contentTitle()).isEqualTo("header")
+    }
+}

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/SoftwareSystemHomePageViewModelTest.kt

@@ -42,7 +42,7 @@ class SoftwareSystemHomePageViewModelTest : ViewModelTest() {
         val generatorContext = generatorContext()
         val softwareSystem: SoftwareSystem = generatorContext.workspace.model.addSoftwareSystem("Software system")
             .apply {
-                documentation.addSection(Section("Title", Format.Markdown, "# Content"))
+                documentation.addSection(createSection("# Title"))
             }
         val viewModel = SoftwareSystemHomePageViewModel(generatorContext, softwareSystem)
 

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/SoftwareSystemPageViewModelTest.kt

@@ -175,9 +175,9 @@ class SoftwareSystemPageViewModelTest : ViewModelTest() {
         val viewModel = SoftwareSystemPageViewModel(generatorContext, softwareSystem, Tab.HOME)
 
         assertThat(getTab(viewModel, Tab.SECTIONS).visible).isFalse()
-        softwareSystem.documentation.addSection(createSection("Section 0000"))
+        softwareSystem.documentation.addSection(createSection("# Section 0000"))
         assertThat(getTab(viewModel, Tab.SECTIONS).visible).isFalse()
-        softwareSystem.documentation.addSection(createSection("Section 0001"))
+        softwareSystem.documentation.addSection(createSection("# Section 0001"))
         assertThat(getTab(viewModel, Tab.SECTIONS).visible).isTrue()
     }
 

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/ViewModelTest.kt

@@ -37,5 +37,5 @@ abstract class ViewModelTest {
             content = "Decision $id content"
         }
 
-    protected fun createSection(title: String = "Section 1") = Section(title, Format.Markdown, "# Content")
+    protected fun createSection(content: String = "# Content") = Section(Format.Markdown, content)
 }

src/test/kotlin/nl/avisi/structurizr/site/generatr/site/model/WorkspaceDocumentationSectionPageViewModelTest.kt

@@ -29,7 +29,7 @@ class WorkspaceDocumentationSectionPageViewModelTest : ViewModelTest() {
         val section = createSection()
         val viewModel = WorkspaceDocumentationSectionPageViewModel(generatorContext, section)
 
-        assertThat(viewModel.pageSubTitle).isEqualTo(section.title)
+        assertThat(viewModel.pageSubTitle).isEqualTo(section.contentTitle())
     }
 
     @Test