README.md

Documentation generators

This module contains generators that create HTML files directly from Flink's source code.

REST API documentation

The RestAPIDocGenerator/OpenApiSpecGenerator can be used to generate a full reference of the REST API of a RestServerEndpoint. A separate file is generated for each endpoint.

To integrate a new endpoint into the generator

1. Add a new DocumentingRestEndpoint class to RestAPIDocGenerator that extends the new endpoint class
2. Add another call to createHtmlFile in RestAPIDocGenerator#main
3. Regenerate the documentation by running mvn package -Dgenerate-rest-docs -pl flink-docs -am -nsu -DskipTests
4. Integrate the generated file into the REST API documentation by adding {{< generated/<file-name> }} to the corresponding markdown file.

The documentation must be regenerated whenever

• a handler is added to/removed from a RestServerEndpoint
• any used MessageHeaders class or any referenced RequestBody, ResponseBody, MessageParameters or MessageParameter class is modified.

Configuration documentation

The ConfigOptionsDocGenerator can be used to generate a reference of ConfigOptions. By default, a separate file is generated for each *Options class found in org.apache.flink.configuration and org.apache.flink.yarn.configuration. The @ConfigGroups annotation can be used to generate multiple files from a single class.

To integrate an *Options class from another package, add another module-package argument pair to ConfigurationOptionLocator#LOCATIONS.

The files can be generated by running mvn package -Dgenerate-config-docs -pl flink-docs -am -nsu -DskipTests, and can be integrated into the documentation using {{ include generated/<file-name> >}}.

The documentation must be regenerated whenever

• an *Options class was added or removed
• a ConfigOption was added to or removed from an *Options class
• a ConfigOption was modified in any way.