[
https://issues.apache.org/jira/browse/KAFKA-3809?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
James Cheng updated KAFKA-3809:
-------------------------------
Attachment: topic_config.html
configuration.html
Attached is the current hand-maintained documentation, and the current
auto-generated documentation.
I can easily update the descriptions of the auto-generated docs to match the
hand-maintained ones. The hand-maintained description are the ones that are
currently visible on the website, and so presumably are the most readable and
most understandable.
The harder part of the work is getting the "Server Default Property" column in
the generated docs. Are there any other configs in the Kafka code where config
values inherit from other config values?
Is there a need at this point for a generic inheritable ConfigDefs mechanism?
The inheritance at this point is encapsulated in code. See
https://github.com/apache/kafka/blob/trunk/core/src/main/scala/kafka/server/KafkaServer.scala#L58-L83
If there is no need for a generic mechanism, I would likely implement this by
creating a custom LogConfigDefs() class that supports an additional argument,
which is the name of the Server Default Property that this config inherits
from. Then I would create a subclass of ConfigDef that would override
toHtmlTable() and toRst() that would output the additional column.
Not sure who to ask for guidance on this, so starting with [~gwenshap] who has
done some previous auto-generated-docs work. Gwen, let me know if there is a
more appropriate person to ask about this.
> 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)
