Allow multiple format and themes in the Config Doc generator

The idea is to allow generating Markdown for easily publishing the config on GitHub. The Javadoc -> Markdown part will probably change a lot soon as we need to support Markdown for the IDEs. This is the fruit of a collaboration with @Athou (Jérémie Panzer), who is marked as a co-author. Co-authored-by: Jérémie Panzer <[email protected]>
quarkusio · Sep 10, 2024 · b038bd0 · b038bd0
1 parent e3b1b23
commit b038bd0
Show file tree

Hide file tree

Showing 29 changed files with 809 additions and 446 deletions.
diff --git a/...in/java/io/quarkus/annotation/processor/documentation/config/discovery/ParsedJavadoc.java b/...in/java/io/quarkus/annotation/processor/documentation/config/discovery/ParsedJavadoc.java
@@ -1,9 +1,10 @@
 package io.quarkus.annotation.processor.documentation.config.discovery;
 
-public record ParsedJavadoc(String description, String since, String deprecated, JavadocFormat originalFormat) {
+public record ParsedJavadoc(String description, String since, String deprecated,
+        String originalDescription, JavadocFormat originalFormat) {
 
     public static ParsedJavadoc empty() {
-        return new ParsedJavadoc(null, null, null, null);
+        return new ParsedJavadoc(null, null, null, null, null);
     }
 
     public boolean isEmpty() {

diff --git a/...kus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java b/...kus/annotation/processor/documentation/config/formatter/JavadocToAsciidocTransformer.java
@@ -95,14 +95,17 @@ public ParsedJavadoc parseConfigItemJavadoc(String rawJavadoc) {
         Javadoc javadoc = StaticJavaParser.parseJavadoc(START_OF_LINE.matcher(rawJavadoc).replaceAll("* "));
 
         String description;
+        String originalDescription;
         JavadocFormat originalFormat;
 
         if (isAsciidoc(javadoc)) {
             description = handleEolInAsciidoc(javadoc);
             originalFormat = JavadocFormat.ASCIIDOC;
+            originalDescription = rawJavadoc;
         } else {
             description = htmlJavadocToAsciidoc(javadoc.getDescription());
             originalFormat = JavadocFormat.JAVADOC;
+            originalDescription = filterRawJavadoc(javadoc.getDescription());
         }
 
         Optional<String> since = javadoc.getBlockTags().stream()
@@ -121,7 +124,8 @@ public ParsedJavadoc parseConfigItemJavadoc(String rawJavadoc) {
             description = null;
         }
 
-        return new ParsedJavadoc(description, since.orElse(null), deprecated.orElse(null), originalFormat);
+        return new ParsedJavadoc(description, since.orElse(null), deprecated.orElse(null), originalDescription,
+                originalFormat);
     }
 
     public ParsedJavadocSection parseConfigSectionJavadoc(String javadocComment) {
@@ -546,4 +550,55 @@ private StringBuilder appendEscapedAsciiDoc(StringBuilder sb, String text) {
         }
         return sb;
     }
+
+    /**
+     * This is not definitely not perfect but it can be used to filter the Javadoc included in Markdown.
+     * <p>
+     * We will need to discuss further how to handle passing the Javadoc to the IDE.
+     * In Quarkus, we have Asciidoc, standard Javadoc and soon we might have Markdown javadoc.
+     */
+    private static String filterRawJavadoc(JavadocDescription javadocDescription) {
+        StringBuilder sb = new StringBuilder();
+
+        for (JavadocDescriptionElement javadocDescriptionElement : javadocDescription.getElements()) {
+            if (javadocDescriptionElement instanceof JavadocInlineTag) {
+                JavadocInlineTag inlineTag = (JavadocInlineTag) javadocDescriptionElement;
+                String content = inlineTag.getContent().trim();
+                switch (inlineTag.getType()) {
+                    case CODE:
+                    case VALUE:
+                    case LITERAL:
+                    case SYSTEM_PROPERTY:
+                    case LINK:
+                    case LINKPLAIN:
+                        sb.append("<code>");
+                        sb.append(escapeHtml(content));
+                        sb.append("</code>");
+                        break;
+                    default:
+                        sb.append(content);
+                        break;
+                }
+            } else {
+                sb.append(javadocDescriptionElement.toText());
+            }
+        }
+
+        return sb.toString().trim();
+    }
+
+    private static String escapeHtml(String s) {
+        StringBuilder out = new StringBuilder(Math.max(16, s.length()));
+        for (int i = 0; i < s.length(); i++) {
+            char c = s.charAt(i);
+            if (c > 127 || c == '"' || c == '\'' || c == '<' || c == '>' || c == '&') {
+                out.append("&#");
+                out.append((int) c);
+                out.append(';');
+            } else {
+                out.append(c);
+            }
+        }
+        return out.toString();
+    }
 }
diff --git a/...java/io/quarkus/annotation/processor/documentation/config/model/ConfigItemCollection.java b/...java/io/quarkus/annotation/processor/documentation/config/model/ConfigItemCollection.java
@@ -17,6 +17,20 @@ default List<AbstractConfigItem> getNonDeprecatedItems() {
                 .toList();
     }
 
+    @JsonIgnore
+    default List<AbstractConfigItem> getNonDeprecatedProperties() {
+        return getItems().stream()
+                .filter(i -> i instanceof ConfigProperty && !i.isDeprecated())
+                .toList();
+    }
+
+    @JsonIgnore
+    default List<AbstractConfigItem> getNonDeprecatedSections() {
+        return getItems().stream()
+                .filter(i -> i instanceof ConfigSection && !i.isDeprecated())
+                .toList();
+    }
+
     void addItem(AbstractConfigItem item);
 
     boolean hasDurationType();

diff --git a/...main/java/io/quarkus/annotation/processor/documentation/config/model/JavadocElements.java b/...main/java/io/quarkus/annotation/processor/documentation/config/model/JavadocElements.java
@@ -2,11 +2,9 @@
 
 import java.util.Map;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
-
 public record JavadocElements(Extension extension, Map<String, JavadocElement> elements) {
 
-    public record JavadocElement(String description, String since, String deprecated, @JsonIgnore String rawJavadoc) {
+    public record JavadocElement(String description, String since, String deprecated, String rawJavadoc) {
     }
 
     public boolean isEmpty() {

diff --git a/...arkus/annotation/processor/documentation/config/scanner/JavadocConfigMappingListener.java b/...arkus/annotation/processor/documentation/config/scanner/JavadocConfigMappingListener.java
@@ -64,7 +64,7 @@ public void onEnclosedMethod(DiscoveryRootElement discoveryRootElement, TypeElem
             configCollector.addJavadocElement(
                     clazz.getQualifiedName().toString() + Markers.DOT + method.getSimpleName().toString(),
                     new JavadocElement(parsedJavadoc.description(), parsedJavadoc.since(), parsedJavadoc.deprecated(),
-                            rawJavadoc.get()));
+                            parsedJavadoc.originalDescription()));
         }
     }
 }
diff --git a/...us/annotation/processor/documentation/config/scanner/JavadocLegacyConfigRootListener.java b/...us/annotation/processor/documentation/config/scanner/JavadocLegacyConfigRootListener.java
@@ -64,7 +64,7 @@ public void onEnclosedField(DiscoveryRootElement discoveryRootElement, TypeEleme
             configCollector.addJavadocElement(
                     clazz.getQualifiedName().toString() + Markers.DOT + field.getSimpleName().toString(),
                     new JavadocElement(parsedJavadoc.description(), parsedJavadoc.since(), parsedJavadoc.deprecated(),
-                            rawJavadoc.get()));
+                            parsedJavadoc.originalDescription()));
         }
     }
 }