Skip to content

Commit

Permalink
feat: render deprecated setting as strikethrough (#252)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ndr-brt
ndr-brt authored Aug 8, 2024
1 parent 388ab13 commit 07648d1
Show file tree
Hide file tree
Showing 10 changed files with 182 additions and 104 deletions.
1 change: 1 addition & 0 deletions DEPENDENCIES
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ maven/mavencentral/org.eclipse.edc/autodoc-processor/+, Apache-2.0, approved, te
maven/mavencentral/org.eclipse.edc/boot-spi/0.8.2-SNAPSHOT, Apache-2.0, approved, technology.edc
maven/mavencentral/org.eclipse.edc/core-spi/0.8.2-SNAPSHOT, Apache-2.0, approved, technology.edc
maven/mavencentral/org.eclipse.edc/policy-model/0.8.2-SNAPSHOT, Apache-2.0, approved, technology.edc
maven/mavencentral/org.eclipse.edc/runtime-metamodel/0.8.2-20240808-SNAPSHOT, Apache-2.0, approved, technology.edc
maven/mavencentral/org.eclipse.edc/runtime-metamodel/0.8.2-SNAPSHOT, Apache-2.0, approved, technology.edc
maven/mavencentral/org.glassfish.web/javax.el/2.2.6, CDDL-1.0 OR GPL-2.0-only WITH Classpath-exception-2.0, approved, #1654
maven/mavencentral/org.hibernate.validator/hibernate-validator-annotation-processor/6.0.2.Final, Apache-2.0 AND LicenseRef-Public-Domain, approved, CQ20221
Expand Down
80 changes: 29 additions & 51 deletions ...c-converters/src/main/java/org/eclipse/edc/plugins/autodoc/html/HtmlManifestRenderer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
import j2html.tags.specialized.ArticleTag;
import j2html.tags.specialized.CodeTag;
import j2html.tags.specialized.HeadTag;
import j2html.tags.specialized.TrTag;
import j2html.tags.specialized.UlTag;
import org.eclipse.edc.plugins.autodoc.spi.ManifestConverterException;
import org.eclipse.edc.plugins.autodoc.spi.ManifestRenderer;
Expand Down Expand Up @@ -54,6 +55,7 @@
import static j2html.TagCreator.span;
import static j2html.TagCreator.style;
import static j2html.TagCreator.table;
import static j2html.TagCreator.tag;
import static j2html.TagCreator.tbody;
import static j2html.TagCreator.td;
import static j2html.TagCreator.th;
Expand All @@ -77,43 +79,15 @@ public HtmlManifestRenderer(OutputStream outputStream) {

@Override
public void renderDocumentHeader() {
head.with(style("""
* {
box-sizing: border-box;
}
nav {
float: left;
width: 20%;
padding: 20px;
}
article {
float: left;
padding: 20px;
width: 80%;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
td {
padding: 5px
}
.odd {
background-color: cccccc;
}
.even {
background-color: eeeeee;
}
"""));
try (var stream = getClass().getClassLoader().getResourceAsStream("style.css")) {
if (stream == null) {
throw new IllegalArgumentException("Resource not found");
}

head.with(style(new String(stream.readAllBytes())));
} catch (Exception exception) {
throw new RuntimeException("Cannot read style.css resource: " + exception.getMessage());
}
}

@Override
Expand Down Expand Up @@ -188,25 +162,29 @@ public void renderConfigurations(List<ConfigurationSetting> configuration) {

var tbody = tbody();

range(0, configuration.size()).mapToObj(index -> {
var setting = configuration.get(index);
var clazz = index % 2 == 0 ? "even" : "odd";
return tr(
td(code(setting.getKey())),
td(setting.isRequired() ? code("x") : null).attr("align", "center"),
td(code(setting.getType())).attr("align", "center"),
td(code(setting.getDefaultValue())),
td(codeOrNull(setting.getPattern())).attr("align", "center"),
td(codeOrNull(setting.getMinimum())).attr("align", "right"),
td(codeOrNull(setting.getMaximum())).attr("align", "right"),
td(setting.getDescription()).attr("width", "40%")
).withClass(clazz);
}).forEach(tbody::with);
range(0, configuration.size())
.mapToObj(index -> renderConfigurationRow(configuration.get(index), index))
.forEach(tbody::with);

content.with(table().with(thead(header)).with(tbody));
}
}

private TrTag renderConfigurationRow(ConfigurationSetting setting, int index) {
var key = code(setting.getKey());

return tr(
td(setting.isDeprecated() ? tag("s").with(key) : key),
td(setting.isRequired() ? code("x") : null).attr("align", "center"),
td(code(setting.getType())).attr("align", "center"),
td(code(setting.getDefaultValue())),
td(codeOrNull(setting.getPattern())).attr("align", "center"),
td(codeOrNull(setting.getMinimum())).attr("align", "right"),
td(codeOrNull(setting.getMaximum())).attr("align", "right"),
td(setting.getDescription()).attr("width", "40%")
).withClass(index % 2 == 0 ? "even" : "odd");
}

@Override
public void renderProvidedServices(List<Service> provides) {
content.with(h4("Provided Services: "));
Expand Down
28 changes: 17 additions & 11 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 @@ -32,6 +32,7 @@
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import static java.lang.String.format;
import static java.util.Optional.ofNullable;
Expand Down Expand Up @@ -117,17 +118,9 @@ public void renderConfigurations(List<ConfigurationSetting> configuration) {
var tableBuilder = new Table.Builder()
.addRow("Key", "Required", "Type", "Default", "Pattern", "Min", "Max", "Description");



configuration.forEach(setting -> tableBuilder.addRow(
code(setting.getKey()),
setting.isRequired() ? code("*") : null,
code(setting.getType()),
ofNullable(setting.getDefaultValue()).map(Markdown::code).orElse(null),
ofNullable(setting.getPattern()).map(Markdown::code).orElse(null),
ofNullable(setting.getMinimum()).map(m -> code(String.valueOf(m))).orElse(null),
ofNullable(setting.getMaximum()).map(m -> code(String.valueOf(m))).orElse(null),
setting.getDescription()));
configuration.stream()
.map(this::renderConfigurationSetting)
.forEach(tableBuilder::addRow);

stringBuilder.append(heading("Configuration: ", 5));
if (!configuration.isEmpty()) {
Expand Down Expand Up @@ -164,6 +157,19 @@ public OutputStream finalizeRendering() {
return output;
}

private Object @NotNull [] renderConfigurationSetting(ConfigurationSetting setting) {
return Stream.of(
setting.isDeprecated() ? Markdown.strikeThrough(setting.getKey()) : code(setting.getKey()),
setting.isRequired() ? code("*") : null,
code(setting.getType()),
ofNullable(setting.getDefaultValue()).map(Markdown::code).orElse(null),
ofNullable(setting.getPattern()).map(Markdown::code).orElse(null),
ofNullable(setting.getMinimum()).map(m -> code(String.valueOf(m))).orElse(null),
ofNullable(setting.getMaximum()).map(m -> code(String.valueOf(m))).orElse(null),
setting.getDescription()
).toArray();
}

private MarkdownElement listOrNone(Object... items) {
if (items.length == 0 || Arrays.stream(items).allMatch(o -> o.toString().isEmpty())) {
return italic(NONE);
Expand Down
35 changes: 35 additions & 0 deletions plugins/autodoc/autodoc-converters/src/main/resources/style.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
* {
box-sizing: border-box;
}
nav {
float: left;
width: 20%;
padding: 20px;
}
article {
float: left;
padding: 20px;
width: 80%;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
td {
padding: 5px
}
.odd {
background-color: cccccc;
}
.even {
background-color: eeeeee;
}
15 changes: 15 additions & 0 deletions ...nverters/src/test/java/org/eclipse/edc/plugins/autodoc/html/HtmlManifestRendererTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,21 @@ void shouldRenderTableWithConfiguration() {
.contains("<table>", "<thead>", "<tbody>", "<tr>", "<td>")
.contains("<td><code>edc.setting.path</code></td>");
}

@Test
void shouldRenderDeprecatedConfiguration() {
var setting = ConfigurationSetting.Builder.newInstance()
.key("edc.setting.path")
.deprecated(true)
.build();
renderer.renderConfigurations(List.of(setting));

var output = renderer.finalizeRendering();

assertThat(output).asString()
.contains("<table>", "<thead>", "<tbody>", "<tr>", "<td>")
.contains("<td><s><code>edc.setting.path</code></s></td>");
}
}

@Nested
Expand Down
30 changes: 30 additions & 0 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 @@ -17,8 +17,11 @@
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.eclipse.edc.plugins.autodoc.spi.ManifestWriter;
import org.eclipse.edc.runtime.metamodel.domain.ConfigurationSetting;
import org.eclipse.edc.runtime.metamodel.domain.EdcModule;
import org.eclipse.edc.runtime.metamodel.domain.EdcServiceExtension;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;

import java.io.ByteArrayOutputStream;
Expand Down Expand Up @@ -58,6 +61,7 @@ void convert_simpleJson() {
@Test
void convert_emptyObject() {
var list = List.of(EdcModule.Builder.newInstance().modulePath("foo").version("0.1.0-bar").build());

var result = writer.convert(list);

assertThat(result).isNotNull().isEqualTo(testOutputStream).extracting(Object::toString).satisfies(markdown -> {
Expand All @@ -68,6 +72,32 @@ void convert_emptyObject() {
});
}

@Nested
class Configuration {

@Test
void shouldRenderConfiguration() {
var configurationSetting = ConfigurationSetting.Builder.newInstance().key("test.key").build();
var extension = EdcServiceExtension.Builder.newInstance().name("name").className("className").configuration(List.of(configurationSetting)).build();
var list = List.of(EdcModule.Builder.newInstance().modulePath("foo").version("0.1.0-bar").extension(extension).build());

var result = writer.convert(list);

assertThat(result).isNotNull().extracting(Object::toString).asString().contains("Configuration:").contains("`test.key`");
}

@Test
void shouldRenderDeprecatedConfiguration() {
var configurationSetting = ConfigurationSetting.Builder.newInstance().key("test.key").deprecated(true).build();
var extension = EdcServiceExtension.Builder.newInstance().name("name").className("className").configuration(List.of(configurationSetting)).build();
var list = List.of(EdcModule.Builder.newInstance().modulePath("foo").version("0.1.0-bar").extension(extension).build());

var result = writer.convert(list);

assertThat(result).isNotNull().extracting(Object::toString).asString().contains("Configuration:").contains("~~test.key~~");
}
}

private List<EdcModule> generateManifest(String filename) {
try (var stream = Thread.currentThread().getContextClassLoader().getResourceAsStream(filename)) {
return new ObjectMapper().readValue(stream, new TypeReference<>() {
Expand Down
1 change: 1 addition & 0 deletions ...a/org/eclipse/edc/plugins/autodoc/core/processor/introspection/ExtensionIntrospector.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ private ConfigurationSetting createConfigurationSetting(VariableElement settingE
.maximum(attributeValue(Long.class, "max", settingMirror, elementUtils))
.minimum(attributeValue(Long.class, "min", settingMirror, elementUtils))
.defaultValue(attributeValue(String.class, "defaultValue", settingMirror, elementUtils))
.deprecated(mirrorFor(Deprecated.class, settingElement) != null)
.build();
}

Expand Down
1 change: 1 addition & 0 deletions ...doc-processor/src/test/java/org/eclipse/edc/plugins/autodoc/core/processor/Constants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ public interface Constants {
String TEST_SETTING_NAME = "Test setting name";
String TEST_SETTING_KEY = "edc.test.setting";
String TEST_SETTING_DEFAULT_VALUE = "default value";
String TEST_DEPRECATED_SETTING_KEY = "edc.test.deprecated.setting";
String TEST_SPI_MODULE = "Test SPI Module";

String TEST_FIELD_PREFIX_SETTING_KEY = "edc.prefix.field.";
Expand Down
91 changes: 49 additions & 42 deletions .../src/test/java/org/eclipse/edc/plugins/autodoc/core/processor/EdcModuleProcessorTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -184,53 +184,60 @@ void verifyManifestContainsExtension() {

@Test
void verifyManifestContainsCorrectElements() {
var task = createTask("testextensions");

task.call();
createTask("testextensions").call();

var modules = readManifest();
assertThat(modules).hasSize(1);
var extensions = modules.get(0).getExtensions();

assertThat(extensions)
.allSatisfy(e -> assertThat(e.getCategories()).isNotNull().isEmpty())
.allSatisfy(e -> assertThat(e.getOverview()).isNull())
.extracting(EdcServiceExtension::getName)
.containsOnly(SampleExtensionWithoutAnnotation.class.getSimpleName(), SecondExtension.class.getSimpleName(), SettingContextExtension.class.getSimpleName());

var ext1 = extensions.stream().filter(e -> e.getName().equals(SampleExtensionWithoutAnnotation.class.getSimpleName()))
.findFirst()
.orElseThrow();

var providedServices = ext1.getProvides();
assertThat(providedServices).hasSize(2)
.extracting(Service::getService)
.containsExactlyInAnyOrder(SomeService.class.getName(), SomeOtherService.class.getName());

var references = ext1.getReferences();
assertThat(references.size()).isEqualTo(2);
assertThat(references).contains(new ServiceReference(OptionalService.class.getName(), false));
assertThat(references).contains(new ServiceReference(RequiredService.class.getName(), true));

assertThat(ext1.getConfiguration()).first().isNotNull().satisfies(configuration -> {
assertThat(configuration).isNotNull();
assertThat(configuration.getKey()).isEqualTo(SampleExtensionWithoutAnnotation.TEST_SETTING);
assertThat(configuration.isRequired()).isTrue();
assertThat(configuration.getDefaultValue()).isEqualTo(TEST_SETTING_DEFAULT_VALUE);
assertThat(configuration.getDescription()).isNotEmpty();
assertThat(modules).hasSize(1).first().extracting(EdcModule::getExtensions).satisfies(extensions -> {
assertThat(extensions)
.allSatisfy(e -> assertThat(e.getCategories()).isNotNull().isEmpty())
.allSatisfy(e -> assertThat(e.getOverview()).isNull())
.extracting(EdcServiceExtension::getName)
.containsOnly(SampleExtensionWithoutAnnotation.class.getSimpleName(), SecondExtension.class.getSimpleName(), SettingContextExtension.class.getSimpleName());

var ext1 = extensions.stream().filter(e -> e.getName().equals(SampleExtensionWithoutAnnotation.class.getSimpleName()))
.findFirst()
.orElseThrow();

var providedServices = ext1.getProvides();
assertThat(providedServices).hasSize(2)
.extracting(Service::getService)
.containsExactlyInAnyOrder(SomeService.class.getName(), SomeOtherService.class.getName());

var references = ext1.getReferences();
assertThat(references.size()).isEqualTo(2);
assertThat(references).contains(new ServiceReference(OptionalService.class.getName(), false));
assertThat(references).contains(new ServiceReference(RequiredService.class.getName(), true));

assertThat(ext1.getConfiguration()).hasSize(2).satisfies(configurations -> {
assertThat(configurations).element(0).satisfies(configuration -> {
assertThat(configuration).isNotNull();
assertThat(configuration.getKey()).isEqualTo(SampleExtensionWithoutAnnotation.TEST_SETTING);
assertThat(configuration.isRequired()).isTrue();
assertThat(configuration.getDefaultValue()).isEqualTo(TEST_SETTING_DEFAULT_VALUE);
assertThat(configuration.getDescription()).isNotEmpty();
assertThat(configuration.isDeprecated()).isFalse();
});

assertThat(configurations).element(1).satisfies(deprecatedConfiguration -> {
assertThat(deprecatedConfiguration.getKey()).isEqualTo(SampleExtensionWithoutAnnotation.DEPRECATED_TEST_SETTING);
assertThat(deprecatedConfiguration.isDeprecated()).isEqualTo(true);
});
});

var ext2 = extensions.stream().filter(e -> e.getName().equals(SecondExtension.class.getSimpleName()))
.findFirst()
.orElseThrow();

assertThat(ext2.getProvides()).isEmpty();

assertThat(ext2.getReferences())
.hasSize(1)
.containsOnly(new ServiceReference(SomeService.class.getName(), true));

assertThat(ext2.getConfiguration()).isEmpty();
});

var ext2 = extensions.stream().filter(e -> e.getName().equals(SecondExtension.class.getSimpleName()))
.findFirst()
.orElseThrow();

assertThat(ext2.getProvides()).isEmpty();

assertThat(ext2.getReferences())
.hasSize(1)
.containsOnly(new ServiceReference(SomeService.class.getName(), true));

assertThat(ext2.getConfiguration()).isEmpty();
}

@Test
Expand Down
Loading

0 comments on commit 07648d1

Please sign in to comment.