You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by "ASF GitHub Bot (JIRA)" <ji...@apache.org> on 2018/02/25 21:28:00 UTC
[jira] [Commented] (KAFKA-4010) ConfigDef.toRst() should create
sections for each group
[ https://issues.apache.org/jira/browse/KAFKA-4010?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16376254#comment-16376254 ]
ASF GitHub Bot commented on KAFKA-4010:
---------------------------------------
hachikuji closed pull request #1696: KAFKA-4010; ConfigDef.toRst() to have grouped sections with dependents info
URL: https://github.com/apache/kafka/pull/1696
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java b/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java
index 256f5231de8..0d8b7a7eb7c 100644
--- a/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java
+++ b/clients/src/main/java/org/apache/kafka/common/config/ConfigDef.java
@@ -539,7 +539,6 @@ private void parseForValidate(String name, Map<String, String> props, Map<String
}
}
- @SuppressWarnings("unchecked")
private void validate(String name, Map<String, Object> parsed, Map<String, ConfigValue> configs) {
if (!configKeys.containsKey(name)) {
return;
@@ -928,38 +927,93 @@ public String toRst() {
StringBuilder b = new StringBuilder();
for (ConfigKey def : configs) {
- b.append("``");
- b.append(def.name);
- b.append("``\n");
- for (String docLine : def.documentation.split("\n")) {
- if (docLine.length() == 0) {
- continue;
+ b.append(getConfigKeyRst(def, b));
+ b.append("\n");
+ }
+ return b.toString();
+ }
+
+
+ /**
+ * Get the configs with new metadata(group, orderInGroup, dependents) formatted with reStructuredText, suitable for embedding in Sphinx
+ * documentation.
+ */
+ public String toEnrichedRst() {
+ List<ConfigKey> configs = sortedConfigsInGroup();
+ StringBuilder b = new StringBuilder();
+ String lastKeyGroupName = "";
+
+ for (ConfigKey def : configs) {
+
+ if (def.group != null) {
+ if (!lastKeyGroupName.equalsIgnoreCase(def.group)) {
+ b.append(def.group);
+ b.append("\n");
+ char[] underLine = new char[def.group.length()];
+ Arrays.fill(underLine, '^');
+ b.append(new String(underLine));
+ b.append("\n\n");
}
- b.append(" ");
- b.append(docLine);
- b.append("\n\n");
+ lastKeyGroupName = def.group;
}
- b.append(" * Type: ");
- b.append(def.type.toString().toLowerCase(Locale.ROOT));
- b.append("\n");
- if (def.defaultValue != null) {
- b.append(" * Default: ");
- if (def.type == Type.STRING) {
- b.append("\"");
- b.append(def.defaultValue);
- b.append("\"");
- } else {
- b.append(def.defaultValue);
+
+ b.append(getConfigKeyRst(def, b));
+
+ if (def.dependents != null && def.dependents.size() > 0) {
+ int j = 0;
+ b.append(" * Dependents: ");
+ for (String dependent : def.dependents) {
+ b.append("``");
+ b.append(dependent);
+ if (++j == def.dependents.size())
+ b.append("``");
+ else
+ b.append("``,");
}
b.append("\n");
}
- b.append(" * Importance: ");
- b.append(def.importance.toString().toLowerCase(Locale.ROOT));
- b.append("\n\n");
+ b.append("\n");
}
return b.toString();
}
+ /**
+ * Shared content on Rst and Enriched Rst.
+ */
+ private StringBuilder getConfigKeyRst(ConfigKey def, StringBuilder b) {
+
+ b.append("``");
+ b.append(def.name);
+ b.append("``\n");
+ for (String docLine : def.documentation.split("\n")) {
+ if (docLine.length() == 0) {
+ continue;
+ }
+ b.append(" ");
+ b.append(docLine);
+ b.append("\n\n");
+ }
+ b.append(" * Type: ");
+ b.append(def.type.toString().toLowerCase(Locale.ROOT));
+ b.append("\n");
+ if (def.defaultValue != null) {
+ b.append(" * Default: ");
+ if (def.type == Type.STRING) {
+ b.append("\"");
+ b.append(def.defaultValue);
+ b.append("\"");
+ } else {
+ b.append(def.defaultValue);
+ }
+ b.append("\n");
+ }
+ b.append(" * Importance: ");
+ b.append(def.importance.toString().toLowerCase(Locale.ROOT));
+ b.append("\n");
+
+ return b;
+ }
+
/**
* Get a list of configs sorted into "natural" order: listing required fields first, then
* ordering by importance, and finally by name.
@@ -988,4 +1042,27 @@ public int compare(ConfigKey k1, ConfigKey k2) {
});
return configs;
}
+
+ /**
+ * Get a list of configs sorted into "group" order: listing group, then
+ * ordering by order in group.
+ */
+ private List<ConfigKey> sortedConfigsInGroup() {
+ // sort first with group, then by name
+ List<ConfigKey> configs = new ArrayList<>(this.configKeys.values());
+ Collections.sort(configs, new Comparator<ConfigKey>() {
+ public int compare(ConfigKey k1, ConfigKey k2) {
+ // sort by group
+ int cmp = k1.group == null ? (k2.group == null ? 0 : 1) : (k2.group == null ? -1 : k1.group.compareTo(k2.group));
+ if (cmp == 0) {
+ // then sort with order in group
+ return Integer.compare(k1.orderInGroup, k2.orderInGroup);
+ } else {
+ return cmp;
+ }
+ }
+ });
+ return configs;
+ }
+
}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
> ConfigDef.toRst() should create sections for each group
> -------------------------------------------------------
>
> Key: KAFKA-4010
> URL: https://issues.apache.org/jira/browse/KAFKA-4010
> Project: Kafka
> Issue Type: Improvement
> Reporter: Shikhar Bhushan
> Assignee: Rekha Joshi
> Priority: Minor
> Fix For: 0.10.2.0
>
>
> Currently the ordering seems a bit arbitrary. There is a logical grouping that connectors are now able to specify with the 'group' field, which we should use as section headers. Also it would be good to generate {{:ref:}} for each section.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)