diff --git a/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java b/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java index 85ea8cda..fa4f8f90 100644 --- a/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java +++ b/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java @@ -55,36 +55,38 @@ 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(bold("Name:")).append(" ").append(moduleName).append(NEWLINE); } - stringBuilder.append(NEWLINE); + + stringBuilder + .append(bold("Artifact:")).append(" ").append(modulePath).append(":").append(version).append(NEWLINE) + .append(NEWLINE); } @Override public void renderCategories(List categories) { - // append categories as italic text var cat = categories .stream() .filter(c -> c != null && !c.isEmpty()) - .collect(Collectors.joining(",")); + .collect(Collectors.joining(", ")); if (cat.isEmpty()) { cat = NONE; } - stringBuilder.append(italic(format("Categories: %s", cat))).append(NEWLINE); + stringBuilder.append(bold("Categories:")).append(" ").append(italic(cat)).append(NEWLINE); stringBuilder.append(NEWLINE); } @@ -114,7 +116,6 @@ public void renderExtensionHeader(@NotNull String className, String name, String @Override public void renderConfigurations(List configuration) { - // add configuration table var tableBuilder = new Table.Builder() .addRow("Key", "Required", "Type", "Default", "Pattern", "Min", "Max", "Description"); @@ -122,7 +123,7 @@ public void renderConfigurations(List 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 { @@ -133,16 +134,14 @@ public void renderConfigurations(List configuration) { @Override public void renderProvidedServices(List provides) { - // add exposed services - stringBuilder.append(heading("Provided services:", 5)).append(NEWLINE); + stringBuilder.append(heading("Provided services", 4)).append(NEWLINE); stringBuilder.append(listOrNone(provides.stream().map(s -> code(s.getService())).toList().toArray())).append(NEWLINE); stringBuilder.append(NEWLINE); } @Override public void renderReferencedServices(List references) { - // add injected services - stringBuilder.append(heading("Referenced (injected) services:", 5)).append(NEWLINE); + stringBuilder.append(heading("Referenced (injected) services", 4)).append(NEWLINE); stringBuilder.append(listOrNone(references.stream().map(s -> format("%s (%s)", code(s.getService()), s.isRequired() ? "required" : "optional")).toList().toArray())).append(NEWLINE); stringBuilder.append(NEWLINE); } diff --git a/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java b/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java index 92035a38..a25d9941 100644 --- a/plugins/autodoc/autodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java +++ b/plugins/autodoc/autodoc-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/plugins/autodoc/autodoc-converters/src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java b/plugins/autodoc/autodoc-converters/src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java index 251bf81d..fdc0ea86 100644 --- a/plugins/autodoc/autodoc-converters/src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java +++ b/plugins/autodoc/autodoc-converters/src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java @@ -26,8 +26,10 @@ import java.io.ByteArrayOutputStream; import java.io.IOException; +import java.util.Collections; import java.util.List; +import static java.util.Collections.emptyList; import static org.assertj.core.api.Assertions.assertThat; class MarkdownManifestRendererTest { @@ -58,18 +60,69 @@ 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:"); + }); + } + + } + + @Nested + class Categories { + @Test + void shouldRenderCategories() { + var module = EdcModule.Builder.newInstance().modulePath("any").version("any") + .categories(List.of("category1", "category2")) + .build(); - 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:"); - }); + var result = writer.convert(List.of(module)); + + assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> { + assertThat(markdown).contains("**Categories:** _category1, category2_"); + }); + } + + @Test + void shouldRenderNone_whenNoCategoriesExist() { + var module = EdcModule.Builder.newInstance().modulePath("any").version("any") + .categories(emptyList()) + .build(); + + var result = writer.convert(List.of(module)); + + assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> { + assertThat(markdown).contains("**Categories:** _None_"); + }); + } } @Nested @@ -83,7 +136,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 +149,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~~"); } }