Skip to content

Commit

Permalink
docs: improve markdown rendering (#267)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndr-brt
ndr-brt committed Sep 25, 2024
1 parent 4dcb212 commit 9ec7808
Show file tree
Hide file tree
Showing 3 changed files with 83 additions and 28 deletions.
29 changes: 14 additions & 15 deletions ...ters/src/main/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRenderer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> 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);
}

Expand Down Expand Up @@ -114,15 +116,14 @@ public void renderExtensionHeader(@NotNull String className, String name, String

@Override
public void renderConfigurations(List<ConfigurationSetting> configuration) {
// add configuration table
var tableBuilder = new Table.Builder()
.addRow("Key", "Required", "Type", "Default", "Pattern", "Min", "Max", "Description");

configuration.stream()
.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 {
Expand All @@ -133,16 +134,14 @@ public void renderConfigurations(List<ConfigurationSetting> configuration) {

@Override
public void renderProvidedServices(List<Service> 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<ServiceReference> 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);
}
Expand Down
1 change: 0 additions & 1 deletion ...utodoc-converters/src/main/java/org/eclipse/edc/plugins/autodoc/spi/ManifestRenderer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down
81 changes: 69 additions & 12 deletions .../src/test/java/org/eclipse/edc/plugins/autodoc/markdown/MarkdownManifestRendererTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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~~");
}
}

Expand Down

0 comments on commit 9ec7808

Please sign in to comment.