Implementation:Apache Paimon ConfigOptionsDocGenerator

Knowledge Sources	Apache_Paimon
Domains	Build Tools, Documentation Generation
Last Updated	2026-02-08 00:00 GMT

Overview

ConfigOptionsDocGenerator is a build-time documentation generator that automatically produces HTML reference documentation for all Paimon configuration options by scanning ConfigOption fields across multiple modules via reflection.

Description

This class implements an annotation-driven documentation system that discovers configuration options at build time. It scans predefined module/package locations (paimon-api, paimon-core, paimon-format, paimon-flink, paimon-hive, paimon-spark) for classes matching the pattern `*Options|*Config|*Parameters`, uses reflection to extract public `ConfigOption` fields, and generates HTML tables with configuration keys, default values, types, and descriptions. The generator supports two organizational modes: classes annotated with `@ConfigGroups` produce multiple files grouped by key prefix using a trie-based Tree data structure for longest-prefix matching, while unannotated classes produce a single table. Additionally, options marked with `@Documentation.Section` are collected into cross-cutting section files for documentation that spans multiple configuration classes. The generator handles enum types specially by listing all values with descriptions if the enum implements `DescribedEnum`. Output filenames use snake_case conversion.

This architecture ensures configuration documentation stays synchronized with the code, as it's regenerated on every build from the actual ConfigOption field definitions and their annotations.

Usage

This generator is invoked as part of the Maven build process to produce the configuration reference section of the Paimon website documentation.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-docs/src/main/java/org/apache/paimon/docs/configuration/ConfigOptionsDocGenerator.java

Signature

public class ConfigOptionsDocGenerator {
    static final OptionsClassLocation[] LOCATIONS = { /* module/package pairs */ };
    static final String DEFAULT_PATH_PREFIX = "src/main/java";

    public static void main(String[] args) throws IOException, ClassNotFoundException;
    static void generateCommonSection(String rootDir, String outputDirectory,
        OptionsClassLocation[] locations, String pathPrefix);
    static List<Pair<ConfigGroup, String>> generateTablesForClass(Class<?> optionsClass);
    static List<OptionWithMetaInfo> extractConfigOptions(Class<?> clazz);
    static String toHtmlString(final OptionWithMetaInfo optionWithMetaInfo);
}

Import

import org.apache.paimon.docs.configuration.ConfigOptionsDocGenerator;

I/O Contract

Inputs

Name	Type	Required	Description
args[0]	String	yes	Output directory for generated HTML files
args[1]	String	yes	Project root directory
LOCATIONS	OptionsClassLocation[]	yes	Array of module/package pairs to scan

Outputs

Name	Type	Description
HTML files	File	Configuration tables in `{snake_case}_configuration.html` format
Section files	File	Cross-cutting section tables in `{section}_section.html` format

Usage Examples

Build Integration

# Invoked via Maven plugin during build
mvn clean install -DskipTests

# Manual invocation
java -cp paimon-docs.jar \
  org.apache.paimon.docs.configuration.ConfigOptionsDocGenerator \
  /path/to/output/dir \
  /path/to/project/root

Configuration Class Pattern

@ConfigGroups(groups = {
    @ConfigGroup(name = "memory", keyPrefix = "execution.memory"),
    @ConfigGroup(name = "batch", keyPrefix = "execution.batch")
})
public class ExecutionOptions {
    @Documentation.Section(value = "execution", position = 1)
    public static final ConfigOption<Integer> PARALLELISM =
        ConfigOptions.key("execution.parallelism")
            .intType()
            .defaultValue(1)
            .withDescription("Default parallelism for jobs");
}

Related Pages

• Principle:Apache_Paimon_Developer_Tooling