From 01166a8bfbdfcaa3c33c4db6a9d9ec52806ffb02 Mon Sep 17 00:00:00 2001
From: Zaiming Shi <zmstone@gmail.com>
Date: Wed, 8 Sep 2021 10:29:25 +0200
Subject: [PATCH] feat(schema): generate document when building the release

---
 apps/emqx/src/emqx_schema.erl                 | 38 ++++++++++++-------
 apps/emqx_machine/src/emqx_machine_schema.erl | 36 +++++++++++++-----
 build                                         |  4 ++
 3 files changed, 55 insertions(+), 23 deletions(-)

diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index e31ab2bf1..f9ee7e7e0 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -76,31 +76,41 @@
 namespace() -> undefined.
 
 roots() ->
-    [{"zones",
+    [ {"listeners",
+      sc(ref("listeners"),
+         #{ desc => "MQTT listeners identified by their protocol type and assigned names"
+          })
+     },
+     {"zones",
       sc(map("name", ref("zone")),
-         #{ desc => "A zone is a set of configs grouped by the zone `$name`. <br>"
-                    "The `$name` can be set to a listner's `zone` config for "
-                    "flexible configuration mapping. <br>"
-                    "NOTE: A builtin zone named `default` is auto created "
+         #{ desc => "A zone is a set of configs grouped by the zone <code>name</code>. <br>"
+                    "For flexible configuration mapping, the <code>name</code> "
+                    "can be set to a listener's <code>zone</code> config . <br>"
+                    "NOTE: A builtin zone named <code>default</code> is auto created "
                     "and can not be deleted."
           })},
-     "mqtt",
-     "flapping_detect",
+     {"mqtt",
+      sc(ref("mqtt"),
+         #{ desc => "Global MQTT configuration.<br>"
+                    "The configs here work as default values which can be overriden "
+                    "in <code>zone</code> configs"
+          })},
+     "rate_limit",
      "force_shutdown",
      "force_gc",
      "conn_congestion",
-     "rate_limit",
      "quota",
-     {"listeners",
-      sc(ref("listeners"),
-         #{ desc => "MQTT listeners identified by their protocol type and assigned names. "
-                    "The listeners enabled by default are named with 'default'"})
-     },
      "broker",
-     "plugins",
+     "plugins", %% TODO: move to emqx_machine_schema
      "stats",
      "sysmon",
      "alarm",
+     {"authentication",
+      sc(hoconsc:lazy(hoconsc:array(map())),
+         #{ desc => "Default authentication configs for all MQTT listeners.<br>"
+                    "For per-listener overrides see <code>authentication</code> "
+                    "in listener configs"
+          })},
      {"authentication",
       sc(hoconsc:lazy(hoconsc:array(map())),
          #{ desc => "Default authentication configs for all MQTT listeners.<br>"
diff --git a/apps/emqx_machine/src/emqx_machine_schema.erl b/apps/emqx_machine/src/emqx_machine_schema.erl
index 348832556..5ef9df7c6 100644
--- a/apps/emqx_machine/src/emqx_machine_schema.erl
+++ b/apps/emqx_machine/src/emqx_machine_schema.erl
@@ -59,13 +59,32 @@
 namespace() -> undefined.
 
 roots() ->
-    %% This is a temp workaround to define part of authorization config
-    %% in emqx_schema and part of it in emqx_authz_schema but then
-    %% merged here in this module
-    %% The proper fix should be to make connection (channel, session) state
-    %% extendable by e.g. allow hooks be stateful.
-    ["cluster", "node", "rpc", "log", "authorization"] ++
-    lists:keydelete("authorization", 1, lists:flatmap(fun roots/1, ?MERGED_CONFIGS)).
+    lists:flatmap(fun roots/1, ?MERGED_CONFIGS) ++
+    [ {"node",
+       sc(hoconsc:ref("node"),
+          #{ desc => "Node name, cookie, config & data directories "
+                     "and the Eralng virtual machine (beam) boot parameters."
+           })}
+    , {"cluster",
+       sc(hoconsc:ref("cluster"),
+          #{ desc => "EMQ X nodes can form a cluster to scale up the total capacity.<br>"
+                     "Here holds the configs to instruct how individual nodes "
+                     "can discover each other, also the database replication "
+                     "role of this node etc."
+           })}
+    , {"log",
+       sc(hoconsc:ref("log"),
+          #{ desc => "Configure logging backends (to console or to file), "
+                     "and logging level for each logger backend."
+           })}
+    , {"rpc",
+       sc(hoconsc:ref("rpc"),
+          #{ desc => "EMQ X uses a library called <code>gen_rpc</code> for "
+                     "inter-broker RPCs.<br>Most of the time the default config "
+                     "should work, but in case you need to do performance "
+                     "fine-turning or experiment a bit, this is where to look."
+           })}
+    ].
 
 fields("cluster") ->
     [ {"name",
@@ -738,5 +757,4 @@ to_atom(Bin) when is_binary(Bin) ->
     binary_to_atom(Bin, utf8).
 
 roots(Module) ->
-    lists:map(fun({_BinName, Root}) -> Root end,
-              maps:to_list(hocon_schema:roots(Module))).
+    lists:map(fun({_BinName, Root}) -> Root end, hocon_schema:roots(Module)).
diff --git a/build b/build
index 27626387e..481249b7c 100755
--- a/build
+++ b/build
@@ -69,6 +69,10 @@ make_rel() {
         echo "gpb should not be included in the release"
         exit 1
     fi
+    local conf_doc
+    conf_doc="$(pwd)/_build/${PROFILE}/rel/emqx/etc/emqx-config-doc.html"
+    echo "===< Generating config document $conf_doc"
+	./_build/"$PROFILE"/rel/emqx/bin/emqx cold_eval "file:write_file('$conf_doc', hocon_schema_html:gen(emqx_machine_schema, \"EMQ X ${PKG_VSN}\"))"
 }
 
 ## unzip previous version .zip files to _build/$PROFILE/rel/emqx/releases before making relup