[
https://issues.apache.org/jira/browse/FLINK-8133?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16281659#comment-16281659
]
ASF GitHub Bot commented on FLINK-8133:
---------------------------------------
Github user kl0u commented on a diff in the pull request:
https://github.com/apache/flink/pull/5052#discussion_r155482491
--- Diff: flink-docs/README.md ---
@@ -0,0 +1,36 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Documentation generators
+
+This module contains generators that create HTML files directly from
Flinks 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`
+4. Integrate the generated file into the REST API documentation using `{%
include generated/<file-name>.html %}`
+
+The documentation must be regenerated whenever
+* a handler was added to/removed from a `RestServerEndpoint`
+* any used `MessageHeaders` class or any referenced `RequestBody`,
`ResponseBody`, `MessageParameters` or `MessageParameter` class was modified.
--- End diff --
-> "any used `MessageHeaders` or referenced `RequestBody`, `ResponseBody`,
`MessageParameters` or `MessageParameter` class is modified."
> Generate documentation for new REST API
> ---------------------------------------
>
> Key: FLINK-8133
> URL: https://issues.apache.org/jira/browse/FLINK-8133
> Project: Flink
> Issue Type: Improvement
> Components: Documentation, REST
> Reporter: Chesnay Schepler
> Assignee: Chesnay Schepler
> Priority: Blocker
> Fix For: 1.5.0
>
>
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
