Merge pull request quarkusio#26305 from michalvavrik/feature/fix-docs…

…-duration-note-generation Fix Docs generation - allow each table to have Duration note
gsmet · Jun 23, 2022 · 76af64d · 76af64d
2 parents cd6c9e5 + a5ff943
commit 76af64d
Show file tree

Hide file tree

Showing 5 changed files with 14 additions and 8 deletions.
diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java
@@ -78,8 +78,9 @@ final public class Constants {
     private static final String DOCS_OUT_DIR = System.getProperty("quarkus.docsOutputDir",
             SYSTEM_PROPERTIES.getProperty("maven.multiModuleProjectDirectory", "."));
     public static final Path GENERATED_DOCS_PATH = Paths.get(DOCS_OUT_DIR + DOCS_SRC_MAIN_ASCIIDOC_GENERATED).toAbsolutePath();
-
-    public static final String DURATION_NOTE_ANCHOR = "duration-note-anchor";
+    public static final String SUMMARY_TABLE_ID_VARIABLE = "summaryTableId";
+    public static final String DURATION_NOTE_ANCHOR = String.format("duration-note-anchor-{%s}",
+            SUMMARY_TABLE_ID_VARIABLE);
     public static final String MEMORY_SIZE_NOTE_ANCHOR = "memory-size-note-anchor";
     public static final String MORE_INFO_ABOUT_TYPE_FORMAT = " link:#%s[icon:question-circle[], title=More information about the %s format]";
     public static final String DURATION_INFORMATION = String.format(Constants.MORE_INFO_ABOUT_TYPE_FORMAT,
@@ -93,7 +94,7 @@ final public class Constants {
             CONFIG_PHASE_BUILD_TIME_ILLUSTRATION);
 
     public static final String DURATION_FORMAT_NOTE = "\nifndef::no-duration-note[]\n[NOTE]" +
-            "\n[[" + DURATION_NOTE_ANCHOR + "]]\n" +
+            "\n[id='" + DURATION_NOTE_ANCHOR + "']\n" +
             ".About the Duration format\n" +
             "====\n" +
             "The format for durations uses the standard `java.time.Duration` format.\n" +

diff --git a/...processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java b/...processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java
@@ -1,5 +1,7 @@
 package io.quarkus.annotation.processor.generate_doc;
 
+import static io.quarkus.annotation.processor.Constants.SUMMARY_TABLE_ID_VARIABLE;
+
 import java.io.IOException;
 import java.io.Writer;
 import java.nio.file.Files;
@@ -10,28 +12,34 @@
 
 final public class ConfigDocWriter {
     private final DocFormatter summaryTableDocFormatter = new SummaryTableDocFormatter();
+    private static final String DECLARE_VAR = "\n:%s: %s\n";
 
     /**
      * Write all extension configuration in AsciiDoc format in `{root}/target/asciidoc/generated/config/` directory
      */
     public void writeAllExtensionConfigDocumentation(ConfigDocGeneratedOutput output)
             throws IOException {
         generateDocumentation(Constants.GENERATED_DOCS_PATH.resolve(output.getFileName()), output.getAnchorPrefix(),
-                output.isSearchable(), output.getConfigDocItems());
+                output.isSearchable(), output.getConfigDocItems(), output.getFileName());
     }
 
     /**
      * Generate documentation in a summary table and descriptive format
      *
      */
     private void generateDocumentation(Path targetPath, String initialAnchorPrefix, boolean activateSearch,
-            List<ConfigDocItem> configDocItems)
+            List<ConfigDocItem> configDocItems, String fileName)
             throws IOException {
         if (configDocItems.isEmpty()) {
             return;
         }
 
         try (Writer writer = Files.newBufferedWriter(targetPath)) {
+
+            // Create var with unique value for each summary table that will make DURATION_FORMAT_NOTE (see below) unique
+            var fileNameWithoutExtension = fileName.substring(0, fileName.length() - Constants.ADOC_EXTENSION.length());
+            writer.append(String.format(DECLARE_VAR, SUMMARY_TABLE_ID_VARIABLE, fileNameWithoutExtension));
+
             summaryTableDocFormatter.format(writer, initialAnchorPrefix, activateSearch, configDocItems);
 
             boolean hasDuration = false, hasMemory = false;

diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc
@@ -624,7 +624,6 @@ Defaults for the different parts are as follows:
 
 The https://jdbc.postgresql.org/documentation/head/connect.html[official documentation] go into more detail and list optional parameters as well.
 
-:no-duration-note: true
 
 [[reactive-configuration]]
 == Reactive Datasource Configuration Reference

diff --git a/docs/src/main/asciidoc/dev-services.adoc b/docs/src/main/asciidoc/dev-services.adoc
@@ -72,7 +72,6 @@ The Keycloak Dev Service will be enabled when the `quarkus-oidc` extension is pr
 the server address has not been explicitly configured. More information can be found at the
 xref:security-openid-connect-dev-services.adoc[OIDC Dev Services Guide].
 
-:no-duration-note: true
 include::{generated-dir}/config/quarkus-keycloak-devservices-keycloak-keycloak-build-time-config.adoc[opts=optional, leveloffset=+1]
 
 == Kogito

diff --git a/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc b/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc
@@ -964,7 +964,6 @@ See link:{hibernate-search-doc-prefix}#configuration-bean-reference-parsing[this
 for more information.
 ====
 
-:no-duration-note: true
 
 [[configuration-reference-coordination-outbox-polling]]
 === Configuration of coordination with outbox polling