[
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:
https://github.com/apache/kafka/pull/1527
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).
[configuration.pdf](https://github.com/apache/kafka/files/323901/configuration.pdf)
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:
https://github.com/apache/kafka/pull/1527.patch
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 <[email protected]>
Date: 2016-06-17T23:02:53Z
Generate docs. Include them in the configuration.html file.
commit 49eb27bdc3c496ec9f3aec34b7570562abb81435
Author: James Cheng <[email protected]>
Date: 2016-06-18T00:11:27Z
Copy the descriptions from the previous hand-maintained webpage into the
code.
commit 596915de11e0d4fea9f30a47dc6eda154959faf3
Author: James Cheng <[email protected]>
Date: 2016-06-18T00:17:31Z
Update some more descriptions, based on of Joel Koshy's changes.
commit 4aad500a09cbd5b80794cc47868dbc43e7e4be4e
Author: James Cheng <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
Date: 2016-06-20T16:41:26Z
segment.ms should inherit from log.roll.ms
commit 7bef85f6047b7d50b543ca7e2ec3ce2199370fec
Author: James Cheng <[email protected]>
Date: 2016-06-20T16:41:59Z
Subclasses just need "protected" access, not full public.
commit fd53519b7e82733698e61b024ada2395e308831f
Author: James Cheng <[email protected]>
Date: 2016-08-04T18:57:48Z
Remove unnecessary semicolons.
commit c7db281e7a11a0ea5f70d4f40614a35ad565a11e
Author: James Cheng <[email protected]>
Date: 2016-08-04T20:00:09Z
Add return value to definition of public methods.
commit b923778a8d593c41a84824b1010a0a6fbdedf488
Author: James Cheng <[email protected]>
Date: 2016-08-04T20:10:42Z
No need for boxing.
commit 8843ef09e161c6e95e2241ef708e4ce4e6bf66c8
Author: James Cheng <[email protected]>
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 <[email protected]>
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 <[email protected]>
Date: 2016-08-05T16:05:30Z
Merge branch 'trunk' into generate_topic_docs
commit bad1627b47fc0f2d7b92fd84e0d4d0991695b3b7
Author: James Cheng <[email protected]>
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
(v6.3.4#6332)
