Merge pull request #43569 from gsmet/fix-summary-id

Config Doc - Fix summaryTableId expansion for type notes
quarkusio · Sep 30, 2024 · 7a5a621 · 7a5a621
2 parents 96d8967 + 474ed5f
commit 7a5a621
Show file tree

Hide file tree

Showing 13 changed files with 64 additions and 47 deletions.
diff --git a/...fig-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java b/...fig-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java
@@ -117,10 +117,11 @@ public void execute() throws MojoExecutionException, MojoFailureException {
                         extension.artifactId(), topLevelPrefix, normalizedFormat.getExtension()));
                 String summaryTableId = formatter
                         .toAnchor(extension.artifactId() + "_" + topLevelPrefix);
+                Context context = new Context(summaryTableId);
 
                 try {
                     Files.writeString(configRootPath,
-                            generateConfigReference(quteEngine, summaryTableId, extension, configRoot, "", true));
+                            generateConfigReference(quteEngine, context, extension, configRoot, "", true));
                 } catch (Exception e) {
                     throw new MojoExecutionException("Unable to render config roots for top level prefix: " + topLevelPrefix
                             + " in extension: " + extension, e);
@@ -156,10 +157,11 @@ public void execute() throws MojoExecutionException, MojoFailureException {
 
             Path configRootPath = resolvedTargetDirectory.resolve(fileName);
             String summaryTableId = formatter.toAnchor(normalizedFileName);
+            Context context = new Context(summaryTableId);
 
             try {
                 Files.writeString(configRootPath,
-                        generateConfigReference(quteEngine, summaryTableId, extension, configRoot, "", true));
+                        generateConfigReference(quteEngine, context, extension, configRoot, "", true));
             } catch (Exception e) {
                 throw new MojoExecutionException("Unable to render config roots for specific file: " + fileName
                         + " in extension: " + extension, e);
@@ -181,10 +183,11 @@ public void execute() throws MojoExecutionException, MojoFailureException {
                         normalizedFormat.getExtension()));
                 String summaryTableId = formatter
                         .toAnchor(extension.artifactId() + "_" + generatedConfigSection.getPath().property());
+                Context context = new Context(summaryTableId);
 
                 try {
                     Files.writeString(configSectionPath,
-                            generateConfigReference(quteEngine, summaryTableId, extension, generatedConfigSection,
+                            generateConfigReference(quteEngine, context, extension, generatedConfigSection,
                                     "_" + generatedConfigSection.getPath().property(), false));
                 } catch (Exception e) {
                     throw new MojoExecutionException(
@@ -201,32 +204,36 @@ public void execute() throws MojoExecutionException, MojoFailureException {
                 Path allConfigPath = resolvedTargetDirectory.resolve(String.format(ALL_CONFIG_FILE_FORMAT,
                         normalizedFormat.getExtension()));
 
-                Files.writeString(allConfigPath, generateAllConfig(quteEngine, mergedModel.getConfigRoots()));
+                Context context = new Context("all-config");
+
+                Files.writeString(allConfigPath, generateAllConfig(quteEngine, context, mergedModel.getConfigRoots()));
             } catch (Exception e) {
                 throw new MojoExecutionException("Unable to render all config", e);
             }
         }
     }
 
-    private static String generateConfigReference(Engine quteEngine, String summaryTableId, Extension extension,
+    private static String generateConfigReference(Engine quteEngine, Context context, Extension extension,
             ConfigItemCollection configItemCollection, String additionalAnchorPrefix, boolean searchable) {
         return quteEngine.getTemplate("configReference")
                 .data("extension", extension)
                 .data("configItemCollection", configItemCollection)
                 .data("searchable", searchable)
-                .data("summaryTableId", summaryTableId)
+                .data("context", context)
+                .data("summaryTableId", context.summaryTableId()) // for backward compatibility, use context instead
                 .data("additionalAnchorPrefix", additionalAnchorPrefix)
                 .data("includeDurationNote", configItemCollection.hasDurationType())
                 .data("includeMemorySizeNote", configItemCollection.hasMemorySizeType())
                 .render();
     }
 
-    private static String generateAllConfig(Engine quteEngine,
+    private static String generateAllConfig(Engine quteEngine, Context context,
             Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRootsByExtensions) {
         return quteEngine.getTemplate("allConfig")
                 .data("configRootsByExtensions", configRootsByExtensions)
                 .data("searchable", true)
-                .data("summaryTableId", "all-config")
+                .data("context", context)
+                .data("summaryTableId", context.summaryTableId()) // for backward compatibility, use context instead
                 .data("additionalAnchorPrefix", "")
                 .data("includeDurationNote", true)
                 .data("includeMemorySizeNote", true)
@@ -323,11 +330,19 @@ private static Engine initializeQuteEngine(Formatter formatter, Format format, S
                                         ctx.evaluate(ctx.getParams().get(1)).toCompletableFuture().join() +
                                         "_section_" + ((ConfigSection) ctx.getBase()).getPath().property()))
                         .build())
+                .addValueResolver(ValueResolver.builder()
+                        .applyToBaseClass(ConfigProperty.class)
+                        .applyToName("formatTypeDescription")
+                        .applyToParameters(1)
+                        .resolveSync(ctx -> formatter.formatTypeDescription((ConfigProperty) ctx.getBase(),
+                                (Context) ctx.evaluate(ctx.getParams().get(0)).toCompletableFuture().join()))
+                        .build())
+                // deprecated, for backward compatibility
                 .addValueResolver(ValueResolver.builder()
                         .applyToBaseClass(ConfigProperty.class)
                         .applyToName("formatTypeDescription")
                         .applyToNoParameters()
-                        .resolveSync(ctx -> formatter.formatTypeDescription((ConfigProperty) ctx.getBase()))
+                        .resolveSync(ctx -> formatter.formatTypeDescription((ConfigProperty) ctx.getBase(), null))
                         .build())
                 .addValueResolver(ValueResolver.builder()
                         .applyToBaseClass(ConfigProperty.class)
@@ -430,4 +445,7 @@ private static String cleanSectionPath(String sectionPath) {
     private String stripAdocSuffix(String fileName) {
         return fileName.substring(0, fileName.length() - ADOC_SUFFIX.length());
     }
+
+    public record Context(String summaryTableId) {
+    }
 }
diff --git a/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java b/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java
@@ -14,6 +14,7 @@
 import io.quarkus.annotation.processor.documentation.config.model.JavadocElements.JavadocElement;
 import io.quarkus.annotation.processor.documentation.config.model.JavadocFormat;
 import io.quarkus.annotation.processor.documentation.config.util.Types;
+import io.quarkus.maven.config.doc.GenerateConfigDocMojo.Context;
 
 abstract class AbstractFormatter implements Formatter {
 
@@ -53,7 +54,7 @@ public String formatDescription(ConfigProperty configProperty) {
     }
 
     @Override
-    public String formatTypeDescription(ConfigProperty configProperty) {
+    public String formatTypeDescription(ConfigProperty configProperty, Context context) {
         String typeContent = "";
 
         if (configProperty.isEnum() && enableEnumTooltips) {
@@ -80,9 +81,9 @@ public String formatTypeDescription(ConfigProperty configProperty) {
         }
 
         if (Duration.class.getName().equals(configProperty.getType())) {
-            typeContent += " " + moreInformationAboutType("duration-note-anchor", Duration.class.getSimpleName());
+            typeContent += " " + moreInformationAboutType(context, "duration-note-anchor", Duration.class.getSimpleName());
         } else if (Types.MEMORY_SIZE_TYPE.equals(configProperty.getType())) {
-            typeContent += " " + moreInformationAboutType("memory-size-note-anchor", "MemorySize");
+            typeContent += " " + moreInformationAboutType(context, "memory-size-note-anchor", "MemorySize");
         }
 
         return typeContent;
@@ -236,7 +237,7 @@ private static String trimFinalDot(String javadoc) {
 
     protected abstract JavadocFormat javadocFormat();
 
-    protected abstract String moreInformationAboutType(String anchorRoot, String type);
+    protected abstract String moreInformationAboutType(Context context, String anchorRoot, String type);
 
     protected abstract String link(String href, String description);
 

diff --git a/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AsciidocFormatter.java b/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AsciidocFormatter.java
@@ -2,6 +2,7 @@
 
 import io.quarkus.annotation.processor.documentation.config.merger.JavadocRepository;
 import io.quarkus.annotation.processor.documentation.config.model.JavadocFormat;
+import io.quarkus.maven.config.doc.GenerateConfigDocMojo.Context;
 
 final class AsciidocFormatter extends AbstractFormatter {
 
@@ -17,8 +18,9 @@ protected JavadocFormat javadocFormat() {
         return JavadocFormat.ASCIIDOC;
     }
 
-    protected String moreInformationAboutType(String anchorRoot, String type) {
-        return String.format(MORE_INFO_ABOUT_TYPE_FORMAT, anchorRoot + "-{summaryTableId}", type);
+    protected String moreInformationAboutType(Context context, String anchorRoot, String type) {
+        return String.format(MORE_INFO_ABOUT_TYPE_FORMAT, anchorRoot + "-" + (context != null ? context.summaryTableId() : ""),
+                type);
     }
 
     protected String tooltip(String value, String javadocDescription) {

diff --git a/...onfig-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java b/...onfig-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/Formatter.java
@@ -5,14 +5,15 @@
 import io.quarkus.annotation.processor.documentation.config.model.ConfigProperty;
 import io.quarkus.annotation.processor.documentation.config.model.ConfigSection;
 import io.quarkus.annotation.processor.documentation.config.model.Extension;
+import io.quarkus.maven.config.doc.GenerateConfigDocMojo.Context;
 
 public interface Formatter {
 
     boolean displayConfigRootDescription(ConfigRootKey configRootKey, int mapSize);
 
     String formatDescription(ConfigProperty configProperty);
 
-    String formatTypeDescription(ConfigProperty configProperty);
+    String formatTypeDescription(ConfigProperty configProperty, Context context);
 
     String formatDefaultValue(ConfigProperty configProperty);
 

diff --git a/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/MarkdownFormatter.java b/...c-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/MarkdownFormatter.java
@@ -3,6 +3,7 @@
 import io.quarkus.annotation.processor.documentation.config.merger.JavadocRepository;
 import io.quarkus.annotation.processor.documentation.config.model.ConfigSection;
 import io.quarkus.annotation.processor.documentation.config.model.JavadocFormat;
+import io.quarkus.maven.config.doc.GenerateConfigDocMojo.Context;
 
 final class MarkdownFormatter extends AbstractFormatter {
 
@@ -23,7 +24,7 @@ public String formatSectionTitle(ConfigSection configSection) {
     }
 
     @Override
-    protected String moreInformationAboutType(String anchorRoot, String type) {
+    protected String moreInformationAboutType(Context context, String anchorRoot, String type) {
         return MORE_INFO_ABOUT_TYPE_FORMAT.formatted(anchorRoot);
     }
 

diff --git a/...-maven-plugin/src/main/resources/templates/asciidoc/default/allConfig.qute.adoc b/...-maven-plugin/src/main/resources/templates/asciidoc/default/allConfig.qute.adoc
@@ -1,4 +1,3 @@
-:summaryTableId: {summaryTableId}
 [.configuration-legend]
 icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
 [.configuration-reference{#if searchable}.searchable{/if}, cols="80,.^10,.^10"]
@@ -21,10 +20,10 @@ h|Default
 {#for item in configRootEntry.value.items}
 {#if !item.deprecated}
 {#if item.isSection}
-{#configSection configSection=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=displayConfigRootDescription /}
+{#configSection context=context configSection=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=displayConfigRootDescription /}
 
 {#else}
-{#configProperty configProperty=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
 
 {/if}
 {/if}
@@ -36,10 +35,8 @@ h|Default
 |===
 
 {#if includeDurationNote}
-{#durationNote summaryTableId /}
+{#durationNote summaryTableId=context.summaryTableId /}
 {/if}
 {#if includeMemorySizeNote}
-{#memorySizeNote summaryTableId /}
-{/if}
-
-:!summaryTableId:
+{#memorySizeNote summaryTableId=context.summaryTableId /}
+{/if}
diff --git a/...-plugin/src/main/resources/templates/asciidoc/default/configReference.qute.adoc b/...-plugin/src/main/resources/templates/asciidoc/default/configReference.qute.adoc
@@ -1,4 +1,3 @@
-:summaryTableId: {summaryTableId}
 [.configuration-legend]
 icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
 [.configuration-reference{#if searchable}.searchable{/if}, cols="80,.^10,.^10"]
@@ -10,10 +9,10 @@ h|Default
 
 {#for item in configItemCollection.nonDeprecatedItems}
 {#if item.isSection}
-{#configSection configSection=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=false /}
+{#configSection context=context configSection=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=false /}
 
 {#else}
-{#configProperty configProperty=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
 
 {/if}
 {#else}
@@ -23,10 +22,8 @@ h|Default
 |===
 
 {#if includeDurationNote}
-{#durationNote summaryTableId /}
+{#durationNote summaryTableId=context.summaryTableId /}
 {/if}
 {#if includeMemorySizeNote}
-{#memorySizeNote summaryTableId /}
-{/if}
-
-:!summaryTableId:
+{#memorySizeNote summaryTableId=context.summaryTableId /}
+{/if}
diff --git a/...gin/src/main/resources/templates/asciidoc/default/tags/configProperty.qute.adoc b/...gin/src/main/resources/templates/asciidoc/default/tags/configProperty.qute.adoc
@@ -9,5 +9,5 @@ a|{#if configProperty.phase.fixedAtBuildTime}icon:lock[title=Fixed at build time
 {configProperty.formatDescription.escapeCellContent.or("")}
 {#envVar configProperty /}
 --
-{#if configProperty.enum}a{/if}|{configProperty.formatTypeDescription.escapeCellContent.or("")}
+{#if configProperty.enum}a{/if}|{configProperty.formatTypeDescription(context).escapeCellContent.or("")}
 |{#if configProperty.defaultValue}{configProperty.formatDefaultValue.escapeCellContent}{#else if !configProperty.optional}required icon:exclamation-circle[title=Configuration property is required]{/if}
diff --git a/...ugin/src/main/resources/templates/asciidoc/default/tags/configSection.qute.adoc b/...ugin/src/main/resources/templates/asciidoc/default/tags/configSection.qute.adoc
@@ -4,10 +4,10 @@ h|Default
 
 {#for item in configSection.nonDeprecatedItems}
 {#if item.isSection}
-{#configSection configSection=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=displayConfigRootDescription /}
+{#configSection context=context configSection=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=displayConfigRootDescription /}
 
 {#else}
-{#configProperty configProperty=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=item extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
 
 {/if}
 {/for}
diff --git a/...oc-maven-plugin/src/main/resources/templates/markdown/default/allConfig.qute.md b/...oc-maven-plugin/src/main/resources/templates/markdown/default/allConfig.qute.md
@@ -17,9 +17,9 @@
 {#for item in configRoot.items}
 {#if !item.deprecated}
 {#if !item.isSection}
-{#configProperty configProperty=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
 {#else}
-{#configSection configSection=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configSection context=context configSection=item extension=extensionConfigRootsEntry.key additionalAnchorPrefix=additionalAnchorPrefix /}
 {/if}
 {/if}
 {/for}
@@ -29,8 +29,8 @@
 {/for}
 
 {#if includeDurationNote}
-{#durationNote summaryTableId /}
+{#durationNote context.summaryTableId /}
 {/if}
 {#if includeMemorySizeNote}
-{#memorySizeNote summaryTableId /}
+{#memorySizeNote context.summaryTableId /}
 {/if}
diff --git a/...en-plugin/src/main/resources/templates/markdown/default/configReference.qute.md b/...en-plugin/src/main/resources/templates/markdown/default/configReference.qute.md
@@ -10,17 +10,17 @@
 </thead>
 <tbody>
 {#for property in configItemCollection.nonDeprecatedProperties}
-{#configProperty configProperty=property extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=property extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
 {/for}
 {#for section in configItemCollection.nonDeprecatedSections}
-{#configSection configSection=section extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=false /}
+{#configSection context=context configSection=section extension=extension additionalAnchorPrefix=additionalAnchorPrefix displayConfigRootDescription=false /}
 {/for}
 </tbody>
 </table>
 
 {#if includeDurationNote}
-{#durationNote summaryTableId /}
+{#durationNote context.summaryTableId /}
 {/if}
 {#if includeMemorySizeNote}
-{#memorySizeNote summaryTableId /}
+{#memorySizeNote context.summaryTableId /}
 {/if}
diff --git a/...lugin/src/main/resources/templates/markdown/default/tags/configProperty.qute.md b/...lugin/src/main/resources/templates/markdown/default/tags/configProperty.qute.md
@@ -12,7 +12,7 @@
 </td>
 <td>
 
-{configProperty.formatTypeDescription.escapeCellContent.or("")}
+{configProperty.formatTypeDescription(context).escapeCellContent.or("")}
 </td>
 <td>
 

diff --git a/...plugin/src/main/resources/templates/markdown/default/tags/configSection.qute.md b/...plugin/src/main/resources/templates/markdown/default/tags/configSection.qute.md
@@ -7,8 +7,8 @@
 </thead>
 
 {#for property in configSection.nonDeprecatedProperties}
-{#configProperty configProperty=property extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configProperty context=context configProperty=property extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
 {/for}
 {#for subsection in configSection.nonDeprecatedSections}
-{#configSection configSection=subsection extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
+{#configSection context=context configSection=subsection extension=extension additionalAnchorPrefix=additionalAnchorPrefix /}
 {/for}
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,7 +12,7 @@ @@
     </td>
     <td>
-    {configProperty.formatTypeDescription.escapeCellContent.or("")}
+    {configProperty.formatTypeDescription(context).escapeCellContent.or("")}
     </td>
     <td>
@@ Expand Down @@