kafka-dev 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] (KAFKA-3809) Auto-generate documentation for topic-level configuration
Date Fri, 05 Aug 2016 23:54:20 GMT

    [ https://issues.apache.org/jira/browse/KAFKA-3809?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15410293#comment-15410293

ASF GitHub Bot commented on KAFKA-3809:

GitHub user wushujames reopened a pull request:


    KAFKA-3809: Auto-generate documentation for topic-level configuration

    @ijuma said that it would make sense to split out this work from KAFKA-3234, since KAFKA-3234
had both a mechanical change (generating docs) as well as a change requiring discussion (deprecating/renaming
config options).
    @jjkoshy, I hope you don't mind that I took over this work. It's been 3 months since the
last activity on KAFKA-3234, so I thought it would be okay to take over.
    This work is essentially is the first 5-6 commits from Joel's https://github.com/apache/kafka/pull/907.
However, since I'm not very experienced with git, I didn't do a direct merge/rebase, but instead
largely hand-merged it. I did some minor cleanup. All credit goes to Joel, all blame goes
to me. :)
    For reference, I attached the auto-generated configuration.html file (as a PDF, because
github won't let me attache html).
    This is my first time writing Scala, so let me know if there are any changes needed.
    I don't know who is the right person to review this. @ijuma, can you help me redirect
this to the appropriate person? Thanks.

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/wushujames/kafka generate_topic_docs

Alternatively you can review and apply these changes as the patch at:


To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #1527
commit 91aa7ff404ba0cdb3d1004591a7e96b5cab98319
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-17T23:02:53Z

    Generate docs. Include them in the configuration.html file.

commit 49eb27bdc3c496ec9f3aec34b7570562abb81435
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-18T00:11:27Z

    Copy the descriptions from the previous hand-maintained webpage into the code.

commit 596915de11e0d4fea9f30a47dc6eda154959faf3
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-18T00:17:31Z

    Update some more descriptions, based on of Joel Koshy's changes.

commit 4aad500a09cbd5b80794cc47868dbc43e7e4be4e
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-18T00:34:14Z

    For each topic-level config, add a column that points to the server-level config value
that it inherits from.

commit 877772aa887486392a606f87f941d1e9b7eee88c
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-18T00:59:34Z

    Fix compile errors. Centralize the descriptions of message.format.version, min.insync.replicas,
and message.timestamp.type

commit e5f05009e34e0a5208ad9a3da8f4bb972e6af85a
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-18T01:51:23Z

    Add a column to the config table that shows the server property that each topic-level
config inherits from.

commit aff49e012d03f64af7ca7e70430fd92159471654
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-20T16:41:26Z

    segment.ms should inherit from log.roll.ms

commit 7bef85f6047b7d50b543ca7e2ec3ce2199370fec
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-06-20T16:41:59Z

    Subclasses just need "protected" access, not full public.

commit fd53519b7e82733698e61b024ada2395e308831f
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-04T18:57:48Z

    Remove unnecessary semicolons.

commit c7db281e7a11a0ea5f70d4f40614a35ad565a11e
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-04T20:00:09Z

    Add return value to definition of public methods.

commit b923778a8d593c41a84824b1010a0a6fbdedf488
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-04T20:10:42Z

    No need for boxing.

commit 8843ef09e161c6e95e2241ef708e4ce4e6bf66c8
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-04T20:23:13Z

    Switch this back. The topic-level description now references the server level description,
not the other way around.

commit d2e4342119927652c2d9de66712b681821ba1411
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-04T23:45:48Z

    Move the headers and column values into data callbacks, so allow subclasses to override.
    Make LogConfig use that functionality to include additional columns.

commit e2dae9a122a67e03094fe41e5379ba232c47575b
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-05T16:05:30Z

    Merge branch 'trunk' into generate_topic_docs

commit bad1627b47fc0f2d7b92fd84e0d4d0991695b3b7
Author: James Cheng <jylcheng@yahoo.com>
Date:   2016-08-05T16:45:40Z

    Fix indentation.


> Auto-generate documentation for topic-level configuration
> ---------------------------------------------------------
>                 Key: KAFKA-3809
>                 URL: https://issues.apache.org/jira/browse/KAFKA-3809
>             Project: Kafka
>          Issue Type: Bug
>            Reporter: James Cheng
>            Assignee: James Cheng
>         Attachments: configuration.html, topic_config.html
> The documentation for topic-level configuration is not auto-generated from the code.
configuration.html still contains hand-maintained documentation.
> I noticed this because I wanted to set message.timestamp.type on a topic, and didn't
see that it was supported, but grepped through the code and it looked like it was.
> The code to auto-generate the docs is quite close, but needs some additional work. In
particular, topic-level configuration is different from all the other ConfigDefs in that topic-level
configuration docs list the broker-level config that they inherit from. We would need to have
a way to show what broker-level config applies to each topic-level config.

This message was sent by Atlassian JIRA

View raw message