Tool to generate configuration reference docs

gradle/libs.versions.toml

@@ -21,6 +21,7 @@
 hadoop = "3.4.1"
 iceberg = "1.7.1"
 dropwizard = "4.0.11"
+picocli = "4.7.6"
 slf4j = "2.0.16"
 swagger = "1.6.14"
 
@@ -40,6 +41,7 @@ bouncycastle-bcprov = { module = "org.bouncycastle:bcprov-jdk18on", version = "1
 caffeine = { module = "com.github.ben-manes.caffeine:caffeine", version = "3.1.8" }
 commons-codec1 = { module = "commons-codec:commons-codec", version = "1.17.2" }
 commons-lang3 = { module = "org.apache.commons:commons-lang3", version = "3.17.0" }
+commons-text = { module = "org.apache.commons:commons-text", version = "1.13.0" }
 dropwizard-bom = { module = "io.dropwizard:dropwizard-bom", version.ref = "dropwizard" }
 eclipselink = { module = "org.eclipse.persistence:eclipselink", version = "4.0.5" }
 errorprone = { module = "com.google.errorprone:error_prone_core", version = "2.36.0" }
@@ -67,10 +69,13 @@ micrometer-bom = { module = "io.micrometer:micrometer-bom", version = "1.14.3" }
 mockito-core = { module = "org.mockito:mockito-core", version = "5.15.2" }
 opentelemetry-bom = { module = "io.opentelemetry:opentelemetry-bom", version = "1.46.0" }
 opentelemetry-semconv = { module = "io.opentelemetry.semconv:opentelemetry-semconv", version = "1.25.0-alpha" }
+picocli = { module = "info.picocli:picocli-codegen", version.ref = "picocli" }
+picocli-codegen = { module = "info.picocli:picocli-codegen", version.ref = "picocli" }
 prometheus-metrics-exporter-servlet-jakarta = { module = "io.prometheus:prometheus-metrics-exporter-servlet-jakarta", version = "1.3.5" }
 s3mock-testcontainers = { module = "com.adobe.testing:s3mock-testcontainers", version = "3.12.0" }
 slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
 smallrye-common-annotation = { module = "io.smallrye.common:smallrye-common-annotation", version = "2.9.0" }
+smallrye-config-core = { module = "io.smallrye.config:smallrye-config-core", version = "3.10.2" }
 spotbugs-annotations = { module = "com.github.spotbugs:spotbugs-annotations", version = "4.8.6" }
 swagger-annotations = { module = "io.swagger:swagger-annotations", version.ref = "swagger" }
 swagger-jaxrs = { module = "io.swagger:swagger-jaxrs", version.ref = "swagger" }

gradle/projects.main.properties

@@ -29,3 +29,7 @@ polaris-jpa-model=extension/persistence/jpa-model
 polaris-tests=integration-tests
 aggregated-license-report=aggregated-license-report
 polaris-version=tools/version
+
+polaris-config-docs-annotations=tools/config-docs/annotations
+polaris-config-docs-generator=tools/config-docs/generator
+polaris-config-docs-site=tools/config-docs/site

tools/config-docs/annotations/build.gradle.kts

@@ -0,0 +1,25 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+plugins {
+  id("polaris-client")
+  `java-library`
+}
+
+description = "Polaris reference docs annotations"

tools/config-docs/annotations/src/main/java/org/apache/polaris/docs/ConfigDocs.java

@@ -0,0 +1,68 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.polaris.docs;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** Contains annotations for {@code :polaris-config-doc-generator}. */
+public interface ConfigDocs {
+  /**
+   * For properties-configs, declares a class containing configuration constants for "properties"
+   * and gives it a page name. The generated markdown files will start with this name.
+   */
+  @Target(ElementType.TYPE)
+  @Retention(RetentionPolicy.SOURCE)
+  @interface ConfigPageGroup {
+    String name();
+  }
+
+  /**
+   * Define the "section" in which the config option appears.
+   *
+   * <p>For properties-configs, this declares that a property constant field appears in the
+   * generated markdown files.
+   *
+   * <p>For smallrye-configs, this declares that a property appears under a different "prefix".
+   */
+  @Target({ElementType.FIELD, ElementType.METHOD})
+  @Retention(RetentionPolicy.SOURCE)
+  @interface ConfigItem {
+    /**
+     * The name of the "section" in which this constant field shall appear. The name of the
+     * generated markdown file will "end" with this name.
+     */
+    String section() default "";
+
+    /** For smallrye-configs only: the section docs are taken from property type's javadoc. */
+    boolean sectionDocFromType() default false;
+  }
+
+  /**
+   * For smallrye-configs, gives map-keys a name that appears as a placeholder in the fully
+   * qualified config name in the generated docs.
+   */
+  @Target(ElementType.METHOD)
+  @Retention(RetentionPolicy.SOURCE)
+  @interface ConfigPropertyName {
+    String value() default "";
+  }
+}

tools/config-docs/generator/build.gradle.kts

@@ -0,0 +1,76 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+plugins {
+  id("polaris-server")
+  `java-library`
+  `java-test-fixtures`
+}
+
+description = "Generates Polaris reference docs"
+
+val genTesting by configurations.creating
+
+dependencies {
+  implementation(project(":polaris-config-docs-annotations"))
+
+  implementation(libs.commons.text)
+
+  implementation(libs.smallrye.config.core)
+  implementation(libs.picocli)
+  annotationProcessor(libs.picocli.codegen)
+
+  testFixturesApi(platform(libs.junit.bom))
+  testFixturesApi("org.junit.jupiter:junit-jupiter")
+  testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+  testFixturesApi(libs.assertj.core)
+  testFixturesApi(libs.mockito.core)
+
+  genTesting(project(":polaris-config-docs-annotations"))
+  genTesting(libs.smallrye.config.core)
+}
+
+tasks.named<Test>("test") {
+  // The test needs the classpath for the necessary dependencies (annotations + smallrye-config).
+  // Resolving the dependencies must happen during task execution (not configuration).
+  jvmArgumentProviders.add(
+    CommandLineArgumentProvider {
+      // So, in theory, all 'org.gradle.category' attributes should use the type
+      // org.gradle.api.attributes.Category,
+      // as Category.CATEGORY_ATTRIBUTE is defined. BUT! Some attributes have an attribute type ==
+      // String.class!
+
+      val categoryAttributeAsString = Attribute.of("org.gradle.category", String::class.java)
+
+      val libraries =
+        genTesting.incoming.artifacts
+          .filter { a ->
+            // dependencies:
+            //  org.gradle.category=library
+            val category =
+              a.variant.attributes.getAttribute(Category.CATEGORY_ATTRIBUTE)
+                ?: a.variant.attributes.getAttribute(categoryAttributeAsString)
+            category != null && category.toString() == Category.LIBRARY
+          }
+          .map { a -> a.file }
+
+      listOf("-Dtesting.libraries=" + libraries.joinToString(":"))
+    }
+  )
+}