From a5ff943dad51d32c4637af02b87d353fa70c788e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20Vav=C5=99=C3=ADk?= Date: Wed, 22 Jun 2022 22:21:03 +0200 Subject: [PATCH] Fix Docs generation - allow each table to have Duration note Fixes: 19330 Currently where 2+ tables with generated configuration properties are included in `adoc` file and these config tables contain `Duration` config key, an exception is thrown and documentation build fails. That's because block id must be unique and [Asciidoctor documentation explain how to solve this problem](https://docs.asciidoctor.org/asciidoc/latest/directives/include-multiple-times-in-same-document/). As I read it in order to use solution, [I had](https://github.com/asciidoctor/asciidoctor/issues/1381) to switch from [legacy block anchor syntax](https://docs.asciidoctor.org/asciidoc/latest/attributes/id/#block-assignment) to longhand syntax. I mentioned you are using workaround `no-duration-note`, but that's not desirable as each summary table should have it's Duration note if needed, however I left possibility to to disable duration note as an option for authors (f.e. you have multiple tables one after another and you feel the note should be included just after the last one...). I checked and there are no changes required to quarkusio.github.io as there is no specific styling applied base on note block id. --- .../io/quarkus/annotation/processor/Constants.java | 7 ++++--- .../processor/generate_doc/ConfigDocWriter.java | 12 ++++++++++-- docs/src/main/asciidoc/datasource.adoc | 1 - docs/src/main/asciidoc/dev-services.adoc | 1 - .../asciidoc/hibernate-search-orm-elasticsearch.adoc | 1 - 5 files changed, 14 insertions(+), 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 index 5cb5214cd72a1..9795032c37a5c 100644 --- 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/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java index 5eb4b4ce1f044..d7d99741ef315 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocWriter.java +++ b/core/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,6 +12,7 @@ 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 @@ -17,7 +20,7 @@ final public class ConfigDocWriter { 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()); } /** @@ -25,13 +28,18 @@ public void writeAllExtensionConfigDocumentation(ConfigDocGeneratedOutput output * */ private void generateDocumentation(Path targetPath, String initialAnchorPrefix, boolean activateSearch, - List configDocItems) + List 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 index 285735b7d3bbf..74d8eaadb9ad1 100644 --- 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 index e5c932ee9fd14..2a19404aaa061 100644 --- 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 index 7050538bf003a..8c79b03be18e2 100644 --- a/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc +++ b/docs/src/main/asciidoc/hibernate-search-orm-elasticsearch.adoc @@ -948,7 +948,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