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