From 17be874b3db017465b2cc36b84eac51f08799cc4 Mon Sep 17 00:00:00 2001
From: Kentaro Hayashi <hayashi@clear-code.com>
Date: Mon, 1 Feb 2021 16:31:05 +0900
Subject: [PATCH] fluent-plugin-config-format: use markdown table

You can see list of parameters at a glance with --compact option

Before:

  * name (type) (required?) description

  * Available values: ...

  * Default value: ...

  * Alias:

  * Deprecated:

  * Obsoleted:

After:

  ### Configuration

  |parameter|type|description|default|
  |---|---|---|---|
  |...|...|...|...|
---
 lib/fluent/command/plugin_config_formatter.rb |  5 ++
 .../param.md-compact.erb                      | 17 +----
 test/command/test_plugin_config_formatter.rb  | 67 +++++++++++++++++++
 3 files changed, 73 insertions(+), 16 deletions(-)

diff --git a/lib/fluent/command/plugin_config_formatter.rb b/lib/fluent/command/plugin_config_formatter.rb
index c9bb749911..bf8f91fe8b 100644
--- a/lib/fluent/command/plugin_config_formatter.rb
+++ b/lib/fluent/command/plugin_config_formatter.rb
@@ -162,6 +162,11 @@ def dump_section_markdown(base_section, level = 0)
     else
       sections, params = base_section.partition {|_name, value| value[:section] }
     end
+    if @compact and not params.empty?
+      dumped << "### Configuration\n\n"
+      dumped << "|parameter|type|description|default|\n"
+      dumped << "|---|---|---|---|\n"
+    end
     params.each do |name, config|
       next if name == :section
       template_name = @compact ? "param.md-compact.erb" : "param.md.erb"
diff --git a/templates/plugin_config_formatter/param.md-compact.erb b/templates/plugin_config_formatter/param.md-compact.erb
index 3b52a6dc56..68ad5ddbaf 100644
--- a/templates/plugin_config_formatter/param.md-compact.erb
+++ b/templates/plugin_config_formatter/param.md-compact.erb
@@ -7,19 +7,4 @@ deprecated = config[:deprecated]
 obsoleted = config[:obsoleted]
 description = config[:desc]
 -%>
-* **<%= name %>** (<%= type %>) (<%= required_label %>): <%= description %>
-<%- if type == :enum -%>
-  * Available values: <%= config[:list].join(", ") %>
-<%- end -%>
-<%- if default -%>
-  * Default value: `<%= default %>`.
-<%- end -%>
-<%- if alias_name -%>
-  * Alias: <%= alias_name %>
-<%- end -%>
-<%- if deprecated -%>
-  * Deprecated: <%= deprecated %>
-<%- end -%>
-<%- if obsoleted -%>
-  * Obsoleted: <%= :obsoleted %>
-<%- end -%>
+|<%= name %>|<%= type %> (<%= required_label %>)|<%= description %><%- if type == :enum -%> (<%= config[:list].map{|x| "`#{x}`"}.join(", ") %>)<%- end -%><%- if alias_name -%><br>Alias: <%= alias_name %><%- end -%><%- if deprecated -%><br>Deprecated: <%= deprecated %><%- end -%><%- if obsoleted -%><br>Obsoleted: <%= :obsoleted %><%- end -%>|<%- if default -%>`<%= default %>`<%- end -%>|
diff --git a/test/command/test_plugin_config_formatter.rb b/test/command/test_plugin_config_formatter.rb
index f32b479f79..41db8fd67d 100644
--- a/test/command/test_plugin_config_formatter.rb
+++ b/test/command/test_plugin_config_formatter.rb
@@ -225,6 +225,30 @@ class SimpleServiceDiscovery < ::Fluent::Plugin::ServiceDiscovery
 path to something
 
 
+TEXT
+      assert_equal(expected, dumped_config)
+    end
+
+    test "input simple (compact)" do
+      dumped_config = capture_stdout do
+        FluentPluginConfigFormatter.new(["--format=markdown", "--compact", "input", "simple"]).call
+      end
+      expected = <<TEXT
+## Plugin helpers
+
+* [inject](https://docs.fluentd.org/v/1.0/plugin-helper-overview/api-plugin-helper-inject)
+* [compat_parameters](https://docs.fluentd.org/v/1.0/plugin-helper-overview/api-plugin-helper-compat_parameters)
+
+* See also: [Input Plugin Overview](https://docs.fluentd.org/v/1.0/input#overview)
+
+## TestFluentPluginConfigFormatter::SimpleInput
+
+### Configuration
+
+|parameter|type|description|default|
+|---|---|---|---|
+|path|string (required)|path to something||
+
 TEXT
       assert_equal(expected, dumped_config)
     end
@@ -298,6 +322,49 @@ class SimpleServiceDiscovery < ::Fluent::Plugin::ServiceDiscovery
 
 
 
+TEXT
+      assert_equal(expected, dumped_config)
+    end
+
+    test "output complex (compact)" do
+      dumped_config = capture_stdout do
+        FluentPluginConfigFormatter.new(["--format=markdown", "--compact", "output", "complex"]).call
+      end
+      expected = <<TEXT
+## Plugin helpers
+
+* [inject](https://docs.fluentd.org/v/1.0/plugin-helper-overview/api-plugin-helper-inject)
+* [compat_parameters](https://docs.fluentd.org/v/1.0/plugin-helper-overview/api-plugin-helper-compat_parameters)
+
+* See also: [Output Plugin Overview](https://docs.fluentd.org/v/1.0/output#overview)
+
+## TestFluentPluginConfigFormatter::ComplexOutput
+
+
+### \\<authentication\\> section (required) (single)
+
+### Configuration
+
+|parameter|type|description|default|
+|---|---|---|---|
+|username|string (required)|username||
+|password|string (required)|password||
+
+
+### \\<parent\\> section (optional) (multiple)
+
+
+#### \\<child\\> section (optional) (multiple)
+
+### Configuration
+
+|parameter|type|description|default|
+|---|---|---|---|
+|names|array (required)|names||
+|difficulty|enum (optional)|difficulty (`easy`, `normal`, `hard`)|`normal`|
+
+
+
 TEXT
       assert_equal(expected, dumped_config)
     end