Merge pull request #8289 from zmstone/0621-fix-config-doc-generation

0621 fix config doc generation

apps/emqx/i18n/emqx_schema_i18n.conf

@@ -2000,7 +2000,7 @@ When publishing or subscribing, prefix all topics with a mountpoint string.
 The prefixed string will be removed from the topic name when the message
 is delivered to the subscriber. The mountpoint is a way that users can use
 to implement isolation of message routing between different listeners.
-For example if a client A subscribes to `t` with `listeners.tcp.<name>.mountpoint`
+For example if a client A subscribes to `t` with `listeners.tcp.\<name>.mountpoint`
 set to `some_tenant`, then the client actually subscribes to the topic
 `some_tenant/t`. Similarly, if another client B (connected to the same listener
 as the client A) sends a message to topic `t`, the message is routed
@@ -2017,7 +2017,7 @@ Variables in mountpoint string:
 
 将消息传递给订阅者时，将从主题名称中删除带前缀的字符串。挂载点是一种用户可以用来实现不同侦听器之间消息路由隔离的方法。
 
-例如，如果客户机 A 使用 <code>listeners.tcp.<name>.mountpoint</code> 设置为'some_tenant'，那么客户端实际上订阅了主题'some_tenant/t'。</br>
+例如，如果客户机 A 使用 <code>listeners.tcp.\<name>.mountpoint</code> 设置为'some_tenant'，那么客户端实际上订阅了主题'some_tenant/t'。</br>
 类似地，如果另一个客户端B（与客户端A连接到同一个侦听器）向主题 't' 发送消息，该消息将路由到所有订阅了'some_租户/t'的客户端，因此客户端 A 将接收主题名为't'的消息</br>
 
 设置为<code>""</code> 以禁用该功能</br>

apps/emqx/src/emqx.appup.src

@@ -1,11 +1,13 @@
 %% -*- mode: erlang -*-
 %% Unless you know what you are doing, DO NOT edit manually!!
 {VSN,
-  [{"5.0.0",[
-    {load_module,emqx_release,brutal_purge,soft_purge,[]},
-    {load_module,emqx_relup}]},
+  [{"5.0.0",
+    [{load_module,emqx_schema,brutal_purge,soft_purge,[]},
+     {load_module,emqx_release,brutal_purge,soft_purge,[]},
+     {load_module,emqx_relup}]},
    {<<".*">>,[]}],
-  [{"5.0.0",[
-    {load_module,emqx_release,brutal_purge,soft_purge,[]},
-    {load_module,emqx_relup}]},
+  [{"5.0.0",
+    [{load_module,emqx_schema,brutal_purge,soft_purge,[]},
+     {load_module,emqx_release,brutal_purge,soft_purge,[]},
+     {load_module,emqx_relup}]},
    {<<".*">>,[]}]}.

apps/emqx/src/emqx_schema.erl

@@ -1650,7 +1650,7 @@ desc("zone") ->
     "A `Zone` defines a set of configuration items (such as the maximum number of connections)"
     " that can be shared between multiple listeners.\n\n"
     "`Listener` can refer to a `Zone` through the configuration item"
-    " <code>listener.<Protocol>.<Listener Name>.zone</code>.\n\n"
+    " <code>listener.\\<Protocol>.\\<Listener Name>.zone</code>.\n\n"
     "The configs defined in the zones will override the global configs with the same key.\n\n"
     "For example, given the following config:\n"
     "```\n"

apps/emqx_conf/i18n/emqx_conf_schema.conf

@@ -400,7 +400,7 @@ or <code>hostname</code>."""
       en: """Unique name of the EMQX node. It must follow <code>%name%@FQDN</code> or
 <code>%name%@IPv4</code> format.
           """
-      zh: """节点名。格式为 <name>@<host>。其中 <host> 可以是 IP 地址，也可以是 FQDN。
+      zh: """节点名。格式为 \<name>@\<host>。其中 <host> 可以是 IP 地址，也可以是 FQDN。
 详见 http://erlang.org/doc/reference_manual/distributed.html。
           """
     }
@@ -1459,11 +1459,10 @@ Each sink is represented by a _log handler_, which can be configured independent
 By default, the logs are stored in `./log` directory (for installation from zip file) or in `/var/log/emqx` (for binary installation).</br>
 This section of the configuration controls the number of files kept for each log handler.
 """
-      zh:
-        """
-        默认情况下，日志存储在 `./log` 目录（用于从 zip 文件安装）或 `/var/log/emqx`（用于二进制安装）。</br>
-        这部分配置，控制每个日志处理进程保留的文件数量。
-        """
+      zh: """
+默认情况下，日志存储在 `./log` 目录（用于从 zip 文件安装）或 `/var/log/emqx`（用于二进制安装）。</br>
+这部分配置，控制每个日志处理进程保留的文件数量。
+"""
     }
     label {
       en: "Log Rotation"

apps/emqx_conf/src/emqx_conf.app.src

@@ -1,6 +1,6 @@
 {application, emqx_conf, [
     {description, "EMQX configuration management"},
-    {vsn, "0.1.0"},
+    {vsn, "0.1.1"},
     {registered, []},
     {mod, {emqx_conf_app, []}},
     {applications, [kernel, stdlib]},

apps/emqx_conf/src/emqx_conf.appup.src

@@ -0,0 +1,11 @@
+%% -*- mode: erlang -*-
+%% Unless you know what you are doing, DO NOT edit manually!!
+{VSN,
+  [{"0.1.0",
+    [{load_module,emqx_conf_schema,brutal_purge,soft_purge,[]},
+     {load_module,emqx_conf,brutal_purge,soft_purge,[]}]},
+   {<<".*">>,[]}],
+  [{"0.1.0",
+    [{load_module,emqx_conf_schema,brutal_purge,soft_purge,[]},
+     {load_module,emqx_conf,brutal_purge,soft_purge,[]}]},
+   {<<".*">>,[]}]}.

apps/emqx_conf/src/emqx_conf.erl

@@ -196,7 +196,9 @@ schema_module() ->
 -spec gen_doc(file:name_all(), module(), file:name_all(), string()) -> ok.
 gen_doc(File, SchemaModule, I18nFile, Lang) ->
     Version = emqx_release:version(),
-    Title = "# " ++ emqx_release:description() ++ " " ++ Version ++ " Configuration",
+    Title =
+        "# " ++ emqx_release:description() ++ " Configuration\n\n" ++
+            "<!--" ++ Version ++ "-->",
     BodyFile = filename:join([rel, "emqx_conf.template.en.md"]),
     {ok, Body} = file:read_file(BodyFile),
     Opts = #{title => Title, body => Body, desc_file => I18nFile, lang => Lang},

apps/emqx_conf/src/emqx_conf_schema.erl

@@ -64,7 +64,8 @@
     emqx_slow_subs_schema
 ]).
 
-namespace() -> cluster.
+%% root config should not have a namespace
+namespace() -> undefined.
 
 roots() ->
     PtKey = ?EMQX_AUTHENTICATION_SCHEMA_MODULE_PT_KEY,

apps/emqx_gateway/i18n/emqx_gateway_schema_i18n.conf

@@ -602,14 +602,14 @@ When set to <code>false</code> clients will be allowed to connect without authen
         desc {
             en: """When publishing or subscribing, prefix all topics with a mountpoint string.
 The prefixed string will be removed from the topic name when the message is delivered to the subscriber. The mountpoint is a way that users can use to implement isolation of message routing between different listeners.
-For example if a client A subscribes to `t` with `listeners.tcp.<name>.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
+For example if a client A subscribes to `t` with `listeners.tcp.\<name>.mountpoint` set to `some_tenant`, then the client actually subscribes to the topic `some_tenant/t`. Similarly, if another client B (connected to the same listener as the client A) sends a message to topic `t`, the message is routed to all the clients subscribed `some_tenant/t`, so client A will receive the message, with topic name `t`. Set to `\"\"` to disable the feature.
 Variables in mountpoint string:
   - <code>${clientid}</code>: clientid
   - <code>${username}</code>: username
 """
             zh: """发布或订阅时，在所有主题前增加前缀字符串。
 当消息投递给订阅者时，前缀字符串将从主题名称中删除。挂载点是用户可以用来实现不同监听器之间的消息路由隔离的一种方式。
-例如，如果客户端 A 在 `listeners.tcp.<name>.mountpoint` 设置为 `some_tenant` 的情况下订阅 `t`，则客户端实际上订阅了 `some_tenant/t` 主题。 类似地，如果另一个客户端 B（连接到与客户端 A 相同的侦听器）向主题 `t` 发送消息，则该消息被路由到所有订阅了 `some_tenant/t` 的客户端，因此客户端 A 将收到该消息，带有 主题名称`t`。 设置为 `\"\"` 以禁用该功能。
+例如，如果客户端 A 在 `listeners.tcp.\<name>.mountpoint` 设置为 `some_tenant` 的情况下订阅 `t`，则客户端实际上订阅了 `some_tenant/t` 主题。 类似地，如果另一个客户端 B（连接到与客户端 A 相同的侦听器）向主题 `t` 发送消息，则该消息被路由到所有订阅了 `some_tenant/t` 的客户端，因此客户端 A 将收到该消息，带有 主题名称`t`。 设置为 `\"\"` 以禁用该功能。
 挂载点字符串中可用的变量：
    - <code>${clientid}</code>：clientid
    - <code>${username}</code>：用户名

apps/emqx_gateway/src/emqx_gateway.appup.src

@@ -2,8 +2,6 @@
 %% Unless you know what you are doing, DO NOT edit manually!!
 {VSN,
   [{"0.1.0",[{load_module,emqx_exproto_pb,brutal_purge,soft_purge,[]}]},
-   {"0.1.0",[{load_module,emqx_exproto_pb,brutal_purge,soft_purge,[]}]},
    {<<".*">>,[]}],
   [{"0.1.0",[{load_module,emqx_exproto_pb,brutal_purge,soft_purge,[]}]},
-   {"0.1.0",[{load_module,emqx_exproto_pb,brutal_purge,soft_purge,[]}]},
    {<<".*">>,[]}]}.

apps/emqx_management/src/emqx_management.app.src

@@ -2,7 +2,7 @@
 {application, emqx_management, [
     {description, "EMQX Management API and CLI"},
     % strict semver, bump manually!
-    {vsn, "5.0.0"},
+    {vsn, "5.0.1"},
     {modules, []},
     {registered, [emqx_management_sup]},
     {applications, [kernel, stdlib, emqx_plugins, minirest, emqx]},

apps/emqx_management/src/emqx_management.appup.src

@@ -0,0 +1,7 @@
+%% -*- mode: erlang -*-
+%% Unless you know what you are doing, DO NOT edit manually!!
+{VSN,
+  [{"5.0.0",[{load_module,emqx_mgmt_cli,brutal_purge,soft_purge,[]}]},
+   {<<".*">>,[]}],
+  [{"5.0.0",[{load_module,emqx_mgmt_cli,brutal_purge,soft_purge,[]}]},
+   {<<".*">>,[]}]}.

apps/emqx_management/src/emqx_mgmt_cli.erl

@@ -170,7 +170,7 @@ if_client(ClientId, Fun) ->
 %% @doc Topics Command
 
 topics(["list"]) ->
-    dump(emqx_route);
+    dump(emqx_route, emqx_topic);
 topics(["show", Topic]) ->
     Routes = ets:lookup(emqx_route, bin(Topic)),
     [print({emqx_topic, Route}) || Route <- Routes];
@@ -658,9 +658,6 @@ olp(_) ->
 %% Dump ETS
 %%--------------------------------------------------------------------
 
-dump(Table) ->
-    dump(Table, Table, ets:first(Table), []).
-
 dump(Table, Tag) ->
     dump(Table, Tag, ets:first(Table), []).