Skip to content

docs: generate the configuration reference from Quarkus config metadata instead of hand-maintaining it #672

Description

@devops-thiago

Problem Statement

The README's environment-variable/config table (~60 rows) is hand-maintained, separately from the @ConfigMapping interfaces in config/ThrillhouseConfig.java and the defaults in application.properties. Every new option is a three-place change, and the table can silently drift from reality — a growing risk as the pipeline roadmap (#669) adds feature gates (REVIEW_DIMENSION_ROUTING_ENABLED, REVIEW_INCREMENTAL_ENABLED, per-model capability flags in #670, …).

Proposed Solution

Generate the config reference from the config metadata Quarkus already produces for @ConfigMapping types (the same quarkus-config-doc machinery that powers extension docs):

  • Emit a generated markdown (or asciidoc) config-reference file during the build, with property name, env-var form, type, default, and the javadoc description.
  • Replace the README's hand-written table with a short curated "most important settings" section linking to the generated full reference.
  • Add a CI check that fails when the generated reference is stale relative to the committed one (or generate it in the docs workflow so it can never be stale).

Descriptions live in one place — the config interface javadoc — and the docs can no longer disagree with the code.

Alternatives Considered

  • Keep hand-maintaining the table — every config addition remains a multi-place change with silent-drift risk.
  • Doc-only lint that greps for missing keys — catches absence but not wrong defaults/descriptions.

Priority

Nice to have (but pays for itself as the config surface grows through the #669 phases)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions