[ https://issues.apache.org/jira/browse/KAFKA-3809?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15339908#comment-15339908 ]
ASF GitHub Bot commented on KAFKA-3809: --------------------------------------- GitHub user wushujames opened 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 attached 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 <jylch...@yahoo.com> Date: 2016-06-17T23:02:53Z Generate docs. Include them in the configuration.html file. commit 49eb27bdc3c496ec9f3aec34b7570562abb81435 Author: James Cheng <jylch...@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 <jylch...@yahoo.com> Date: 2016-06-18T00:17:31Z Update some more descriptions, based on of Joel Koshy's changes. commit 4aad500a09cbd5b80794cc47868dbc43e7e4be4e Author: James Cheng <jylch...@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 <jylch...@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 <jylch...@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 <jylch...@yahoo.com> Date: 2016-06-20T16:41:26Z segment.ms should inherit from log.roll.ms commit 7bef85f6047b7d50b543ca7e2ec3ce2199370fec Author: James Cheng <jylch...@yahoo.com> Date: 2016-06-20T16:41:59Z Subclasses just need "protected" access, not full public. ---- > 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)