Merge pull request #51098 from wjglerum/config-doc-default-ascii-doc-attribute

Allow to set default value for config options with AsciiDoc attributes

Author: gsmet

build-parent/pom.xml

@@ -85,13 +85,13 @@
         <junit-pioneer.version>2.2.0</junit-pioneer.version>
 
         <!-- Database images for JDBC/Reactive/Hibernate tests and devservices -->
-        <postgres.image>docker.io/postgres:17</postgres.image>
-        <mariadb.image>docker.io/mariadb:10.11</mariadb.image>
+        <postgres.image>docker.io/library/postgres:17</postgres.image>
+        <mariadb.image>docker.io/library/mariadb:10.11</mariadb.image>
         <db2.image>icr.io/db2_community/db2:12.1.0.0</db2.image>
         <mssql.image>mcr.microsoft.com/mssql/server:2022-latest</mssql.image>
-        <mysql.image>docker.io/mysql:8.4</mysql.image>
+        <mysql.image>docker.io/library/mysql:8.4</mysql.image>
         <oracle.image>docker.io/gvenzl/oracle-free:23-slim-faststart</oracle.image>
-        <mongo.image>docker.io/mongo:7.0</mongo.image>
+        <mongo.image>docker.io/library/mongo:7.0</mongo.image>
 
         <!-- Align various dependencies that are not really part of the bom-->
         <junit4.version>4.13.2</junit4.version>
@@ -110,6 +110,16 @@
         <!-- Artemis test dependencies -->
         <artemis.version>2.44.0</artemis.version>
 
+        <!-- Dev Services Images -->
+        <!-- TODO switch to apache/activemq-artemis to match the artemis version-->
+        <amqp.image>quay.io/artemiscloud/activemq-artemis-broker:1.0.25</amqp.image>
+        <apicurio-registry.image>quay.io/apicurio/apicurio-registry-mem:2.6.13.Final</apicurio-registry.image>
+        <narayana-lra.image>quay.io/jbosstm/lra-coordinator:latest</narayana-lra.image>
+        <rabbitmq.image>docker.io/library/rabbitmq:3.12-management</rabbitmq.image>
+        <pulsar.image>docker.io/apachepulsar/pulsar:3.2.4</pulsar.image>
+        <redis.image>docker.io/library/redis:7</redis.image>
+        <infinispan.image>quay.io/infinispan/server:latest</infinispan.image>
+
         <!-- Code Coverage Properties-->
         <jacoco.agent.argLine></jacoco.agent.argLine>
 

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/discovery/DiscoveryConfigProperty.java

@@ -13,6 +13,7 @@ public class DiscoveryConfigProperty {
     private final SourceElementType sourceElementType;
     private final String defaultValue;
     private final String defaultValueForDoc;
+    private final boolean escapeDefaultValueForDoc;
     private final Deprecation deprecation;
     private final String mapKey;
     private final boolean unnamedMapKey;
@@ -24,8 +25,8 @@ public class DiscoveryConfigProperty {
 
     public DiscoveryConfigProperty(String path, String sourceType, String sourceElementName,
             SourceElementType sourceElementType,
-            String defaultValue,
-            String defaultValueForDoc, Deprecation deprecation, String mapKey, boolean unnamedMapKey,
+            String defaultValue, String defaultValueForDoc, boolean escapeDefaultValueForDoc,
+            Deprecation deprecation, String mapKey, boolean unnamedMapKey,
             ResolvedType type, boolean converted, boolean enforceHyphenateEnumValue,
             boolean section, boolean sectionGenerated) {
         this.path = path;
@@ -34,6 +35,7 @@ public DiscoveryConfigProperty(String path, String sourceType, String sourceElem
         this.sourceElementType = sourceElementType;
         this.defaultValue = defaultValue;
         this.defaultValueForDoc = defaultValueForDoc;
+        this.escapeDefaultValueForDoc = escapeDefaultValueForDoc;
         this.deprecation = deprecation;
         this.mapKey = mapKey;
         this.unnamedMapKey = unnamedMapKey;
@@ -68,6 +70,10 @@ public String getDefaultValueForDoc() {
         return defaultValueForDoc;
     }
 
+    public boolean isEscapeDefaultValueForDoc() {
+        return escapeDefaultValueForDoc;
+    }
+
     public Deprecation getDeprecation() {
         return deprecation;
     }
@@ -150,6 +156,7 @@ public static class Builder {
         private final ResolvedType type;
         private String defaultValue;
         private String defaultValueForDoc;
+        private boolean escapeDefaultValueForDoc = true;
         private Deprecation deprecation;
         private String mapKey;
         private boolean unnamedMapKey = false;
@@ -180,6 +187,11 @@ public Builder defaultValueForDoc(String defaultValueForDoc) {
             return this;
         }
 
+        public Builder escapeDefaultValueForDoc(boolean escapeDefaultValueForDoc) {
+            this.escapeDefaultValueForDoc = escapeDefaultValueForDoc;
+            return this;
+        }
+
         public Builder deprecated(String since, String replacement, String reason) {
             this.deprecation = new Deprecation(since, replacement);
             return this;
@@ -220,7 +232,7 @@ public DiscoveryConfigProperty build() {
             }
 
             return new DiscoveryConfigProperty(name, sourceType, sourceElementName, sourceElementType, defaultValue,
-                    defaultValueForDoc,
+                    defaultValueForDoc, escapeDefaultValueForDoc,
                     deprecation, mapKey, unnamedMapKey, type, converted, enforceHyphenateEnumValue, section, sectionGenerated);
         }
     }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/model/ConfigProperty.java

@@ -27,6 +27,7 @@ public final class ConfigProperty extends AbstractConfigItem {
     private final EnumAcceptedValues enumAcceptedValues;
 
     private final String defaultValue;
+    private final boolean escapeDefaultValue;
 
     private final String javadocSiteLink;
 
@@ -35,7 +36,7 @@ public ConfigProperty(ConfigPhase phase, String sourceType, String sourceElement
             boolean list, boolean optional, boolean secret,
             String mapKey, boolean unnamedMapKey, boolean withinMap, boolean converted, @JsonProperty("enum") boolean isEnum,
             EnumAcceptedValues enumAcceptedValues,
-            String defaultValue, String javadocSiteLink,
+            String defaultValue, boolean escapeDefaultValue, String javadocSiteLink,
             Deprecation deprecation) {
         super(sourceType, sourceElementName, sourceElementType, path, type, deprecation);
         this.phase = phase;
@@ -52,6 +53,7 @@ public ConfigProperty(ConfigPhase phase, String sourceType, String sourceElement
         this.isEnum = isEnum;
         this.enumAcceptedValues = enumAcceptedValues;
         this.defaultValue = defaultValue;
+        this.escapeDefaultValue = escapeDefaultValue;
         this.javadocSiteLink = javadocSiteLink;
     }
 
@@ -121,6 +123,10 @@ public String getDefaultValue() {
         return defaultValue;
     }
 
+    public boolean isEscapeDefaultValue() {
+        return escapeDefaultValue;
+    }
+
     public String getJavadocSiteLink() {
         return javadocSiteLink;
     }

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/resolver/ConfigResolver.java

@@ -213,7 +213,7 @@ private void resolveProperty(ConfigRoot configRoot, Map<String, ConfigSection> e
                     discoveryConfigProperty.isUnnamedMapKey(), context.isWithinMap(),
                     discoveryConfigProperty.isConverted(),
                     discoveryConfigProperty.getType().isEnum(),
-                    enumAcceptedValues, defaultValue,
+                    enumAcceptedValues, defaultValue, discoveryConfigProperty.isEscapeDefaultValueForDoc(),
                     JavadocUtil.getJavadocSiteLink(typeBinaryName),
                     deprecation);
             context.getItemCollection().addItem(configProperty);

core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/scanner/ConfigMappingListener.java

@@ -152,8 +152,12 @@ public void onEnclosedMethod(DiscoveryRootElement discoveryRootElement, TypeElem
 
         AnnotationMirror configDocDefaultAnnotation = methodAnnotations.get(Types.ANNOTATION_CONFIG_DOC_DEFAULT);
         if (configDocDefaultAnnotation != null) {
-            builder.defaultValueForDoc(
-                    configDocDefaultAnnotation.getElementValues().values().iterator().next().getValue().toString());
+            String value = (String) utils.element().getAnnotationValues(configDocDefaultAnnotation).get("value");
+            builder.defaultValueForDoc(value);
+            Boolean escape = (Boolean) utils.element().getAnnotationValues(configDocDefaultAnnotation).get("escape");
+            if (escape != null) {
+                builder.escapeDefaultValueForDoc(escape);
+            }
         }
 
         if (resolvedType.isMap()) {

core/runtime/src/main/java/io/quarkus/runtime/annotations/ConfigDocDefault.java

@@ -22,4 +22,6 @@
 public @interface ConfigDocDefault {
 
     String value();
+
+    boolean escape() default true;
 }

devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/generator/AbstractFormatter.java

@@ -274,7 +274,11 @@ private String formatSingleDefaultValue(ConfigProperty configProperty, String de
             }
         }
 
-        return escapeDefaultValue(defaultValue);
+        if (configProperty.isEscapeDefaultValue()) {
+            return escapeDefaultValue(defaultValue);
+        } else {
+            return defaultValue;
+        }
     }
 
     private static String trimFinalDot(String javadoc) {

docs/src/main/asciidoc/_attributes.adoc

@@ -11,14 +11,27 @@
 :mandrel-flavor: ${mandrel.image-tag-for-documentation}
 :surefire-version: ${version.surefire.plugin}
 :gradle-version: ${gradle-wrapper.version}
+:db2-image: ${db2.image}
+:mariadb-image: ${mariadb.image}
+:mssql-image: ${mssql.image}
+:oracle-image: ${oracle.image}
+:postgres-image: ${postgres.image}
 :elasticsearch-version: ${elasticsearch-server.version}
 :elasticsearch-image: ${elasticsearch.image}
 :opensearch-image: ${opensearch.image}
 :infinispan-version: ${infinispan.version}
 :infinispan-protostream-version: ${infinispan.protostream.version}
 :logstash-image: ${logstash.image}
 :kibana-image: ${kibana.image}
-:keycloak-docker-image: ${keycloak.docker.image}
+:keycloak-image: ${keycloak.docker.image}
+:amqp-image: ${amqp.image}
+:apicurio-registry-image: ${apicurio-registry.image}
+:narayana-lra-image: ${narayana-lra.image}
+:mongo-image: ${mongo.image}
+:rabbitmq-image: ${rabbitmq.image}
+:pulsar-image: ${pulsar.image}
+:redis-image: ${redis.image}
+:infinispan-image: ${infinispan.image}
 :jandex-version: ${jandex.version}
 :jandex-gradle-plugin-version: ${jandex-gradle-plugin.version}
 :kotlin-version: ${kotlin.version}

docs/src/main/asciidoc/amqp-dev-services.adoc

@@ -50,9 +50,9 @@ You can set the port by configuring the `quarkus.amqp.devservices.port` property
 Dev Services for AMQP uses https://quay.io/repository/artemiscloud/activemq-artemis-broker[activemq-artemis-broker] images.
 You can configure the image and version using the `quarkus.amqp.devservices.image-name` property:
 
-[source, properties]
+[source, properties, subs=attributes+]
 ----
-quarkus.amqp.devservices.image-name=quay.io/artemiscloud/activemq-artemis-broker:latest
+quarkus.amqp.devservices.image-name={amqp-image}
 ----
 
 IMPORTANT: The configured image must be _compatible_ with the `activemq-artemis-broker` one.
@@ -65,12 +65,12 @@ The ports 5672 and 8161 (web console) are exposed.
 Dev Services for AMQP supports xref:compose-dev-services.adoc[Compose Dev Services].
 It relies on a `compose-devservices.yml`, such as:
 
-[source,yaml]
+[source,yaml,subs=attributes+]
 ----
 name: <application name>
 services:
   artemis:
-    image: quay.io/artemiscloud/activemq-artemis-broker:1.0.28
+    image: {amqp-image}
     ports:
       - "5672"
       - "8161"

docs/src/main/asciidoc/amqp.adoc

@@ -366,14 +366,14 @@ Open `http://localhost:8080/quotes.html` in your browser and request some quotes
 When not running in dev or test mode, you will need to start your AMQP broker.
 You can follow the instructions from the https://activemq.apache.org/components/artemis/documentation/latest/using-server.html[Apache ActiveMQ Artemis website] or create a `docker-compose.yaml` file with the following content:
 
-[source, yaml]
+[source, yaml ,subs=attributes+]
 ----
 version: '2'
 
 services:
 
   artemis:
-    image: quay.io/artemiscloud/activemq-artemis-broker:1.0.25
+    image: {amqp-image}
     ports:
       - "8161:8161"
       - "61616:61616"