Generate full Polaris configuration reference docs by adutra · Pull Request #3838 · apache/polaris

adutra · 2026-02-19T16:27:24Z

This PR leverages the existing docs generator tool to expose a comprehensive configuration reference documentation for the Polaris site including feature flags.

This extends the existing config-docs generator to support two types of configuration sources:

SmallRye Config properties (from @ConfigMapping annotated interfaces)
PolarisConfiguration static fields (both FeatureConfiguration and BehaviorChangeConfiguration)

Key changes:

Modified DocGenDoclet to extract configuration metadata from FeatureConfiguration and BehaviorChangeConfiguration static fields using reflection and javadoc processing.
Add new Gradle task to copy generated docs to the site content directory with proper Hugo front matter
Reorganize site configuration documentation into a dedicated section with separate pages for configuration overview and reference
Add CI workflow step to verify generated configuration docs are up-to-date

The generated documentation includes property names, descriptions, default values, types, and catalog config mappings where applicable.

Checklist

🛡️ Don't disclose security issues! (contact [email protected])
🔗 Clearly explained why the changes are needed, or linked related issues: Fixes #
🧪 Added/updated tests with good coverage, or manually tested (and explained how)
💡 Added comments for complex logic
🧾 Updated CHANGELOG.md (if needed)
📚 Updated documentation in site/content/in-dev/unreleased (if needed)

adutra · 2026-02-19T16:28:28Z

Note to reviewers: all files in the site/content/in-dev/unreleased/configuration/config-sections are automatically generated with ./gradlew :polaris-config-docs-site:copyConfigSectionsToSite.

adutra · 2026-02-19T16:33:52Z

Screenshot of the new configuration reference page:

The tables are sometimes too wide, I'm thinking about how to improve this.

adutra · 2026-02-19T16:36:59Z

Updated layout for feature flags:

adutra · 2026-02-19T16:38:40Z

Screenshot of the table layout for "regular" (Smallrye) config properties:

adutra · 2026-02-19T16:40:56Z

site/content/in-dev/unreleased/configuration/configuration-reference.md

+
+{{% include-config-section "flags-polaris_features" %}}
+
+### ``polaris.behavior-changes``


FYI there is debate about whether or not this section should be exposed to users:

https://lists.apache.org/thread/8fgszl9jw9718dstlh3dxn0o1g8wkrh4

But for now, I'm including everything.

adutra · 2026-02-19T17:05:04Z

.../service/src/main/java/org/apache/polaris/service/identity/ServiceIdentityConfiguration.java

 * polaris.service-identity.aws-iam.access-key-id=<access-key-id>
 * polaris.service-identity.aws-iam.secret-access-key=<secret-access-key>
 * polaris.service-identity.aws-iam.session-token=<optional-session-token>
- *


This extra line messes up the rendered content – I gave up on investigating why 😅

snazy

This is great!

Just a few comments, the code changes and site changes LGTM!

snazy · 2026-02-19T18:43:38Z

site/content/in-dev/unreleased/configuration/configuring-polaris.md

+
+## Quarkus Configuration Options
+
+There are many Quarkus configuration properties that can be useful, for example:


Suggested change

There are many Quarkus configuration properties that can be useful, for example:

Some often useful Quarkus configuration properties are listed below.

Please refer to the [Quarkus documentation](https://quarkus.io/guides/) for more details.

snazy · 2026-02-19T18:44:13Z

site/content/in-dev/unreleased/configuration/configuring-polaris.md

+| `GC_METASPACE_SIZE`              | The initial metaspace size. There is no default (example: "20").                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `GC_MAX_METASPACE_SIZE`          | The maximum metaspace size. There is no default (example: "100").                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `GC_CONTAINER_OPTIONS`           | Specify Java GC to use. The value of this variable should contain the necessary JRE command-line options to specify the required GC, which will override the default of `-XX:+UseParallelGC` (example: `-XX:+UseG1GC`).                                                                                                                                                                                                                                                                                                                |
+Here are some examples:


Suggested change

Here are some examples:

Here are some examples:

(newline to separate the paragraph from the table above)

snazy · 2026-02-19T18:48:26Z

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


 dependencies {
  implementation(project(":polaris-config-docs-annotations"))
+  implementation(project(":polaris-core"))


A bit sad that this is needed as an implementation dependency.

Suggested change

implementation(project(":polaris-core"))

implementation(project(":polaris-core")) {

isTransitive = false

}

flyingImer

this is cool! I wonder if we can have folders for auto gen docs and manually curated docs by straightforward names? This can help avoid accidentally changing doc files supposed to be auto generated, also making it obvious for new comers rather than an untold knowledge by the community

flyingImer · 2026-02-23T23:34:45Z

...ntent/in-dev/unreleased/configuration/configuring-polaris-for-production/configuring-helm.md

[main Helm chart documentation](../../helm/) needs to be updated to [main Helm chart documentation](../configuration/helm/)

You were right that the link is broken, but it seems the right link is [main Helm chart documentation](../../../helm).

FYI this page will go away with #3812.

flyingImer · 2026-02-23T23:37:05Z

site/content/in-dev/unreleased/configuration/configuring-polaris-for-production/_index.md

Suggested change

The [Polaris Evolution](../configuration/evolution) page discusses backward compatibility and

I don't agree with your suggestion: this link is correct.

Oh sorry, you were right, I was looking at my other PR #3812

adutra · 2026-02-24T09:59:29Z

I wonder if we can have folders for auto gen docs and manually curated docs by straightforward names?

Thanks for the suggestion! Do you have an example of the layout you have in mind?

…hensive configuration reference documentation for the Polaris site. This extends the existing `config-docs` generator to support two types of configuration sources: 1. SmallRye Config properties (from `@ConfigMapping` annotated interfaces) 2. `PolarisConfiguration` static fields (both `FeatureConfiguration` and `BehaviorChangeConfiguration`) Key changes: - Modified `DocGenDoclet` to extract configuration metadata from `FeatureConfiguration` and `BehaviorChangeConfiguration` static fields using reflection and javadoc processing. - Add new Gradle task to copy generated docs to the site content directory with proper Hugo front matter - Reorganize site configuration documentation into a dedicated section with separate pages for configuration overview and reference - Add CI workflow step to verify generated configuration docs are up-to-date The generated documentation includes property names, descriptions, default values, types, and catalog config mappings where applicable.

adutra · 2026-02-24T10:56:35Z

FYI: rebased on top of #3812

github-project-automation bot added this to Basic Kanban Board Feb 19, 2026

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Feb 19, 2026

adutra force-pushed the configuration-page-generation branch from 8d2b927 to 48b4553 Compare February 19, 2026 16:36

adutra commented Feb 19, 2026

View reviewed changes

adutra force-pushed the configuration-page-generation branch 3 times, most recently from 4e61c72 to 8f0ed02 Compare February 19, 2026 17:01

adutra commented Feb 19, 2026

View reviewed changes

adutra force-pushed the configuration-page-generation branch 2 times, most recently from d1dd7ba to b79acf7 Compare February 19, 2026 17:30

snazy reviewed Feb 19, 2026

View reviewed changes

adutra mentioned this pull request Feb 20, 2026

fix(JDBC): Correct the JDBC property names in the documentation #3850

Open

6 tasks

snazy previously approved these changes Feb 20, 2026

View reviewed changes

github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Feb 20, 2026

snazy mentioned this pull request Feb 20, 2026

NoSQL: Add maintenance service to Polaris admin tool #3395

Merged

adutra dismissed snazy’s stale review via e263b9c February 20, 2026 17:41

adutra force-pushed the configuration-page-generation branch from 76bebf5 to e263b9c Compare February 20, 2026 17:41

adutra added this to the 1.4.0 milestone Feb 20, 2026

adutra mentioned this pull request Feb 21, 2026

Improve documentation of storage location feature flags and their behaviors #3856

Draft

6 tasks

flyingImer reviewed Feb 23, 2026

View reviewed changes

adutra force-pushed the configuration-page-generation branch from 11d4c11 to 12f631c Compare February 24, 2026 10:16

snazy previously approved these changes Feb 24, 2026

View reviewed changes

adutra added 3 commits February 24, 2026 11:47

review

ca5cc3e

spotless

6e94591

adutra added 4 commits February 24, 2026 11:48

fix links

94948d5

update generated docs

27fd6f3

more links + a few typos

b3dfee1

fix link after rebase

bf55e0f

adutra dismissed snazy’s stale review via bf55e0f February 24, 2026 10:55

adutra force-pushed the configuration-page-generation branch from 12f631c to bf55e0f Compare February 24, 2026 10:55

snazy approved these changes Feb 24, 2026

View reviewed changes

adutra merged commit a6ca7cb into apache:main Feb 24, 2026
17 checks passed

adutra deleted the configuration-page-generation branch February 24, 2026 11:21

github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Feb 24, 2026


		{{% include-config-section "flags-polaris_features" %}}

		### ``polaris.behavior-changes``


		## Quarkus Configuration Options

		There are many Quarkus configuration properties that can be useful, for example:

	There are many Quarkus configuration properties that can be useful, for example:
	Some often useful Quarkus configuration properties are listed below.
	Please refer to the [Quarkus documentation](https://quarkus.io/guides/) for more details.

-  implementation(project(":polaris-core"))
+  implementation(project(":polaris-core")) {
+    isTransitive = false
+  }


	The [Polaris Evolution](../configuration/evolution) page discusses backward compatibility and

Conversation

adutra commented Feb 19, 2026

Checklist

Uh oh!

adutra commented Feb 19, 2026

Uh oh!

adutra commented Feb 19, 2026

Uh oh!

adutra commented Feb 19, 2026

Uh oh!

adutra commented Feb 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snazy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flyingImer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adutra commented Feb 24, 2026

Uh oh!

adutra commented Feb 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants