flink-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "ASF GitHub Bot (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (FLINK-8133) Generate documentation for new REST API
Date Thu, 07 Dec 2017 10:36:00 GMT

    [ 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)

Mime
View raw message