docs: improve markdown rendering (#267)

eclipse-edc · Sep 23, 2024 · 35238b8 · 35238b8
1 parent 4dcb212
commit 35238b8
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 20 deletions.
diff --git a/...ters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java b/...ters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java
@@ -55,21 +55,24 @@ public MarkdownManifestRenderer(OutputStream output) {
 
     @Override
     public void renderDocumentHeader() {
-        stringBuilder.append(heading(DOCUMENT_HEADING, 1)).append(NEWLINE);
-        stringBuilder.append(NEWLINE);
+
     }
 
     @Override
     public void renderModuleHeading(@Nullable String moduleName, @NotNull String modulePath, @NotNull String version) {
-        var name = ofNullable(moduleName).orElse(modulePath);
+        var modulePathTokens = modulePath.split(":");
+        var artifactId = modulePathTokens.length == 2 ? modulePathTokens[1] : modulePath;
 
-        var moduleHeading = heading(format("Module `%s:%s`", name, version), 2);
+        var moduleHeading = heading(format("Module `%s`", artifactId), 2);
         stringBuilder.append(moduleHeading).append(NEWLINE);
 
         if (moduleName != null) {
-            stringBuilder.append(italic(modulePath)).append(NEWLINE);
+            stringBuilder.append(italic("name: ")).append(moduleName).append(NEWLINE);
         }
-        stringBuilder.append(NEWLINE);
+
+        stringBuilder
+                .append(italic("artifact: ")).append(modulePath).append(":").append(version).append(NEWLINE)
+                .append(NEWLINE);
     }
 
     @Override
@@ -122,7 +125,7 @@ public void renderConfigurations(List<ConfigurationSetting> configuration) {
                 .map(this::renderConfigurationSetting)
                 .forEach(tableBuilder::addRow);
 
-        stringBuilder.append(heading("Configuration: ", 5));
+        stringBuilder.append(heading("Configuration: ", 3));
         if (!configuration.isEmpty()) {
             stringBuilder.append(NEWLINE).append(NEWLINE).append(tableBuilder.build()).append(NEWLINE);
         } else {

diff --git a/...utodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java b/...utodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java
@@ -29,7 +29,6 @@
  * The ManifestRenderer interface provides callback methods to render a manifest document.
  */
 public interface ManifestRenderer {
-    String DOCUMENT_HEADING = "EDC Autodoc Manifest";
     String EXTENSION_POINTS = "Extension points";
     String EXTENSIONS = "Extensions";
     String NONE = "None";

diff --git a/.../src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java b/.../src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java
@@ -58,18 +58,40 @@ void convert_simpleJson() {
         assertThat(result).isNotNull().isEqualTo(testOutputStream);
     }
 
-    @Test
-    void convert_emptyObject() {
-        var list = List.of(EdcModule.Builder.newInstance().modulePath("foo").version("0.1.0-bar").build());
+    @Nested
+    class Heading {
 
-        var result = writer.convert(list);
+        @Test
+        void shouldRenderHeading() {
+            var list = List.of(EdcModule.Builder.newInstance().modulePath("foo:bar").version("0.1.0-baz").build());
+
+            var result = writer.convert(list);
+
+            assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> {
+                assertThat(markdown).contains("Module `bar`");
+                assertThat(markdown).contains("_artifact: _foo:bar:0.1.0-baz");
+                assertThat(markdown).contains("### Extension points");
+                assertThat(markdown).contains("### Extensions");
+                assertThat(markdown).doesNotContain("Configuration:");
+            });
+        }
+
+        @Test
+        void shouldRenderHeading_whenModuleNameIsSet() {
+            var list = List.of(EdcModule.Builder.newInstance().name("module name").modulePath("foo:bar").version("0.1.0-baz").build());
+
+            var result = writer.convert(list);
+
+            assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> {
+                assertThat(markdown).contains("Module `bar`");
+                assertThat(markdown).contains("_name: _module name");
+                assertThat(markdown).contains("_artifact: _foo:bar:0.1.0-baz");
+                assertThat(markdown).contains("### Extension points");
+                assertThat(markdown).contains("### Extensions");
+                assertThat(markdown).doesNotContain("Configuration:");
+            });
+        }
 
-        assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> {
-            assertThat(markdown).contains("Module `foo:0.1.0-bar`");
-            assertThat(markdown).contains("### Extension points");
-            assertThat(markdown).contains("### Extensions");
-            assertThat(markdown).doesNotContain("Configuration:");
-        });
     }
 
     @Nested
@@ -83,7 +105,9 @@ void shouldRenderConfiguration() {
 
             var result = writer.convert(list);
 
-            assertThat(result).isNotNull().extracting(Object::toString).asString().contains("Configuration:").contains("`test.key`");
+            assertThat(result).isNotNull().extracting(Object::toString).asString()
+                    .contains("### Configuration:")
+                    .contains("`test.key`");
         }
 
         @Test
@@ -94,7 +118,9 @@ void shouldRenderDeprecatedConfiguration() {
 
             var result = writer.convert(list);
 
-            assertThat(result).isNotNull().extracting(Object::toString).asString().contains("Configuration:").contains("~~test.key~~");
+            assertThat(result).isNotNull().extracting(Object::toString).asString()
+                    .contains("### Configuration:")
+                    .contains("~~test.key~~");
         }
     }