Merge pull request #44623 from gsmet/doc-improvements

Config Doc - Assorted improvements related to Kubernetes extensions
quarkusio · Nov 22, 2024 · d3e99ba · d3e99ba
2 parents a5e8b1c + 51078fa
commit d3e99ba
Show file tree

Hide file tree

Showing 12 changed files with 55 additions and 18 deletions.
diff --git a/core/deployment/pom.xml b/core/deployment/pom.xml
@@ -225,6 +225,9 @@
                                     <version>${project.version}</version>
                                 </path>
                             </annotationProcessorPaths>
+                            <compilerArgs>
+                                <arg>-AsplitOnConfigRootDescription=true</arg>
+                            </compilerArgs>
                         </configuration>
                     </execution>
                 </executions>

diff --git a/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java b/...processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java
@@ -27,7 +27,7 @@
 import io.quarkus.annotation.processor.util.Config;
 import io.quarkus.annotation.processor.util.Utils;
 
-@SupportedOptions({ Options.LEGACY_CONFIG_ROOT, Options.GENERATE_DOC })
+@SupportedOptions({ Options.LEGACY_CONFIG_ROOT, Options.GENERATE_DOC, Options.SPLIT_ON_CONFIG_ROOT_DESCRIPTION })
 public class ExtensionAnnotationProcessor extends AbstractProcessor {
 
     private static final String DEBUG = "debug-extension-annotation-processor";

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Options.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Options.java
@@ -4,4 +4,5 @@ public final class Options {
 
     public static final String LEGACY_CONFIG_ROOT = "legacyConfigRoot";
     public static final String GENERATE_DOC = "generateDoc";
+    public static final String SPLIT_ON_CONFIG_ROOT_DESCRIPTION = "splitOnConfigRootDescription";
 }
diff --git a/...r/src/main/java/io/quarkus/annotation/processor/documentation/config/model/Extension.java b/...r/src/main/java/io/quarkus/annotation/processor/documentation/config/model/Extension.java
@@ -5,24 +5,29 @@
 import com.fasterxml.jackson.annotation.JsonIgnore;
 
 public record Extension(String groupId, String artifactId, String name,
-        NameSource nameSource, boolean commonOrInternal, String guideUrl, boolean detected) implements Comparable<Extension> {
+        NameSource nameSource, boolean commonOrInternal, String guideUrl,
+        boolean splitOnConfigRootDescription, boolean detected) implements Comparable<Extension> {
 
     private static final String ARTIFACT_COMMON_SUFFIX = "-common";
     private static final String ARTIFACT_INTERNAL_SUFFIX = "-internal";
+    private static final String NAME_COMMON_SUFFIX = "Common";
+    private static final String NAME_INTERNAL_SUFFIX = "Internal";
+    private static final String NAME_SEPARATOR = " - ";
 
     public static Extension of(String groupId, String artifactId, String name,
-            NameSource nameSource, String guideUrl) {
+            NameSource nameSource, String guideUrl, boolean splitOnConfigRootDescription) {
         boolean commonOrInternal = artifactId.endsWith(ARTIFACT_COMMON_SUFFIX) || artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX);
         if (commonOrInternal) {
             nameSource = nameSource == NameSource.EXTENSION_METADATA ? NameSource.EXTENSION_METADATA_COMMON_INTERNAL
                     : (nameSource == NameSource.POM_XML ? NameSource.POM_XML_COMMON_INTERNAL : nameSource);
         }
 
-        return new Extension(groupId, artifactId, name, nameSource, commonOrInternal, guideUrl, true);
+        return new Extension(groupId, artifactId, name, nameSource, commonOrInternal, guideUrl, splitOnConfigRootDescription,
+                true);
     }
 
     public static Extension createNotDetected() {
-        return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false, null, false);
+        return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false, null, false, false);
     }
 
     @Override
@@ -57,32 +62,39 @@ public boolean isMixedModule() {
         return "io.quarkus".equals(groupId) && ("quarkus-core".equals(artifactId) || "quarkus-messaging".equals(artifactId));
     }
 
-    @JsonIgnore
-    public boolean splitOnConfigRootDescription() {
-        // quarkus-core has a lot of config roots and they are very specific
-        // we need to split them properly in the generated documentation
-        return "io.quarkus".equals(groupId) && "quarkus-core".equals(artifactId);
-    }
-
     @JsonIgnore
     public Extension normalizeCommonOrInternal() {
         if (!commonOrInternal()) {
             return this;
         }
 
         String normalizedArtifactId = artifactId;
+        String normalizedName = name;
         if (artifactId.endsWith(ARTIFACT_COMMON_SUFFIX)) {
             normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_COMMON_SUFFIX.length());
+
+            if (name != null && name.endsWith(NAME_COMMON_SUFFIX)) {
+                normalizedName = name.substring(0, name.length() - NAME_COMMON_SUFFIX.length());
+            }
         }
         if (artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX)) {
             normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_INTERNAL_SUFFIX.length());
+
+            if (name != null && name.endsWith(NAME_INTERNAL_SUFFIX)) {
+                normalizedName = name.substring(0, name.length() - NAME_INTERNAL_SUFFIX.length());
+            }
+        }
+
+        if (normalizedName != null && normalizedName.endsWith(NAME_SEPARATOR)) {
+            normalizedName = normalizedName.substring(0, normalizedName.length() - NAME_SEPARATOR.length());
         }
 
-        if (normalizedArtifactId.equals(artifactId)) {
+        if (normalizedArtifactId.equals(artifactId) && Objects.equals(normalizedName, name)) {
             return this;
         }
 
-        return new Extension(groupId, normalizedArtifactId, name, nameSource, commonOrInternal, null, detected);
+        return new Extension(groupId, normalizedArtifactId, normalizedName, nameSource, commonOrInternal, null,
+                splitOnConfigRootDescription, detected);
     }
 
     @Override

diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/util/ExtensionUtil.java b/core/processor/src/main/java/io/quarkus/annotation/processor/util/ExtensionUtil.java
@@ -18,6 +18,7 @@
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
+import io.quarkus.annotation.processor.Options;
 import io.quarkus.annotation.processor.documentation.config.model.Extension;
 import io.quarkus.annotation.processor.documentation.config.model.Extension.NameSource;
 import io.quarkus.annotation.processor.documentation.config.model.ExtensionModule;
@@ -151,7 +152,9 @@ private ExtensionModule getExtensionModuleFromPom(Path pom, Document doc) {
         }
 
         return ExtensionModule.of(groupId, artifactId, moduleType,
-                Extension.of(groupId, extensionArtifactId, extensionName, extensionNameSource, guideUrl));
+                Extension.of(groupId, extensionArtifactId, extensionName, extensionNameSource, guideUrl,
+                        Boolean.parseBoolean(
+                                processingEnv.getOptions().getOrDefault(Options.SPLIT_ON_CONFIG_ROOT_DESCRIPTION, "false"))));
     }
 
     private Optional<ExtensionMetadata> getExtensionMetadata() {

diff --git a/core/runtime/pom.xml b/core/runtime/pom.xml
@@ -294,6 +294,9 @@
                                     <version>${project.version}</version>
                                 </path>
                             </annotationProcessorPaths>
+                            <compilerArgs>
+                                <arg>-AsplitOnConfigRootDescription=true</arg>
+                            </compilerArgs>
                         </configuration>
                     </execution>
                 </executions>

diff --git a/extensions/kubernetes/vanilla/deployment/pom.xml b/extensions/kubernetes/vanilla/deployment/pom.xml
@@ -10,7 +10,7 @@
     <modelVersion>4.0.0</modelVersion>
 
     <artifactId>quarkus-kubernetes-deployment</artifactId>
-    <name>Quarkus - Kubernetes - Vanilla - Deployment</name>
+    <name>Quarkus - Kubernetes - Deployment</name>
 
     <dependencies>
         <dependency>
@@ -132,6 +132,9 @@
                                     <version>${project.version}</version>
                                 </path>
                             </annotationProcessorPaths>
+                            <compilerArgs>
+                                <arg>-AsplitOnConfigRootDescription=true</arg>
+                            </compilerArgs>
                         </configuration>
                     </execution>
                 </executions>

diff --git a/...etes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java b/...etes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java
@@ -9,6 +9,9 @@
 import io.smallrye.config.ConfigMapping;
 import io.smallrye.config.WithDefault;
 
+/**
+ * Knative
+ */
 @ConfigMapping(prefix = "quarkus.knative")
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public interface KnativeConfig extends PlatformConfiguration {

diff --git a/...s/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KubernetesConfig.java b/...s/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KubernetesConfig.java
@@ -16,6 +16,9 @@
 import io.smallrye.config.ConfigMapping;
 import io.smallrye.config.WithDefault;
 
+/**
+ * Kubernetes
+ */
 @ConfigMapping(prefix = "quarkus.kubernetes")
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public interface KubernetesConfig extends PlatformConfiguration {

diff --git a/...es/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/OpenShiftConfig.java b/...es/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/OpenShiftConfig.java
@@ -17,6 +17,9 @@
 import io.smallrye.config.ConfigMapping;
 import io.smallrye.config.WithDefault;
 
+/**
+ * OpenShift
+ */
 @ConfigMapping(prefix = "quarkus.openshift")
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public interface OpenShiftConfig extends PlatformConfiguration {

diff --git a/extensions/kubernetes/vanilla/pom.xml b/extensions/kubernetes/vanilla/pom.xml
@@ -11,7 +11,7 @@
     <modelVersion>4.0.0</modelVersion>
 
     <artifactId>quarkus-kubernetes-vanilla-parent</artifactId>
-    <name>Quarkus - Kubernetes - Vanilla</name>
+    <name>Quarkus - Kubernetes</name>
     <packaging>pom</packaging>
     <modules>
         <module>deployment</module>

diff --git a/extensions/kubernetes/vanilla/runtime/pom.xml b/extensions/kubernetes/vanilla/runtime/pom.xml
@@ -11,7 +11,7 @@
     </parent>
 
     <artifactId>quarkus-kubernetes</artifactId>
-    <name>Quarkus - Kubernetes - Vanilla - Runtime</name>
+    <name>Quarkus - Kubernetes - Runtime</name>
     <description>Generate Kubernetes resources from annotations</description>
 
     <dependencies>
@@ -45,6 +45,9 @@
                                     <version>${project.version}</version>
                                 </path>
                             </annotationProcessorPaths>
+                            <compilerArgs>
+                                <arg>-AsplitOnConfigRootDescription=true</arg>
+                            </compilerArgs>
                         </configuration>
                     </execution>
                 </executions>