From 35238b8bb3c0d8b46836843254241609c868589d Mon Sep 17 00:00:00 2001 From: andrea bertagnolli Date: Mon, 23 Sep 2024 14:53:03 +0200 Subject: [PATCH] docs: improve markdown rendering (#267) --- .../markdown/MarkdownManifestRenderer.java | 17 ++++--- .../plugins/autodoc/spi/ManifestRenderer.java | 1 - .../MarkdownManifestRendererTest.java | 50 ++++++++++++++----- 3 files changed, 48 insertions(+), 20 deletions(-) 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..84e6100a 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,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 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/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..34f3fa69 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 @@ -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~~"); } }