tree: 0b0aa35fef2ac5afcb5d2e24cae0c58dba54c3ea [path history] [tgz]
  1. src/
  2. pom.xml
  3. README.md
flink-docs/README.md

Documentation generators

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

REST API documentation

The RestAPIDocGenerator 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 use 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 ConfigOptionsDocGenerator#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.