Merge pull request #8186 from zmstone/0612-build-separate-doc-gen-build-step

build: build docs in a separate step

Makefile

@@ -115,7 +115,7 @@ ELIXIR_COMMON_DEPS := ensure-hex ensure-mix-rebar3 ensure-mix-rebar
 
 .PHONY: $(REL_PROFILES)
 $(REL_PROFILES:%=%): $(COMMON_DEPS)
-	@$(REBAR) as $(@) do release
+	@$(BUILD) $(@) rel
 
 ## Not calling rebar3 clean because
 ## 1. rebar3 clean relies on rebar3, meaning it reads config, fetches dependencies etc.

apps/emqx_conf/src/emqx_conf.erl

@@ -197,7 +197,7 @@ schema_module() ->
 gen_doc(File, SchemaModule, I18nFile, Lang) ->
     Version = emqx_release:version(),
     Title = "# " ++ emqx_release:description() ++ " " ++ Version ++ " Configuration",
-    BodyFile = filename:join([code:lib_dir(emqx_conf), "etc", "emqx_conf.md"]),
+    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},
     Doc = hocon_schema_md:gen(SchemaModule, Opts),

build

@@ -68,11 +68,19 @@ log() {
     echo "===< $msg"
 }
 
-make_doc() {
+make_docs() {
-    local libs_dir1 libs_dir2
+    local libs_dir1 libs_dir2 libs_dir3
-    libs_dir1="$("$FIND" "_build/default/lib/" -maxdepth 2 -name ebin -type d)"
+    libs_dir1="$("$FIND" "_build/$PROFILE/lib/" -maxdepth 2 -name ebin -type d)"
-    libs_dir2="$("$FIND" "_build/$PROFILE/lib/" -maxdepth 2 -name ebin -type d)"
+    if [ -d "_build/default/lib/" ]; then
-    libs_dir3="$("$FIND" "_build/$PROFILE/checkouts/" -maxdepth 2 -name ebin -type d 2>/dev/null || true)"
+        libs_dir2="$("$FIND" "_build/default/lib/" -maxdepth 2 -name ebin -type d)"
+    else
+        libs_dir2=''
+    fi
+    if [ -d "_build/$PROFILE/checkouts" ]; then
+        libs_dir3="$("$FIND" "_build/$PROFILE/checkouts/" -maxdepth 2 -name ebin -type d 2>/dev/null || true)"
+    else
+        libs_dir3=''
+    fi
     case $PROFILE in
         emqx-enterprise)
             SCHEMA_MODULE='emqx_enterprise_conf_schema'
@@ -83,8 +91,8 @@ make_doc() {
     esac
     # shellcheck disable=SC2086
     erl -noshell -pa $libs_dir1 $libs_dir2 $libs_dir3 -eval \
-        "Dir = filename:join(['_build', '${PROFILE}', lib, emqx_dashboard, priv, www, static]), \
+        "Dir = filename:join([apps, emqx_dashboard, priv, www, static]), \
-         I18nFile = filename:join(['_build', '${PROFILE}', lib, emqx_dashboard, etc, 'i18n.conf.all']), \
+         I18nFile = filename:join([apps, emqx_dashboard, etc, 'i18n.conf.all']), \
          ok = emqx_conf:dump_schema(Dir, $SCHEMA_MODULE, I18nFile), \
          halt(0)."
 }
@@ -97,6 +105,11 @@ assert_no_compile_time_only_deps() {
 }
 
 make_rel() {
+    # compile all beams
+    ./rebar3 as "$PROFILE" compile
+    # generate docs (require beam compiled), generated to etc and priv dirs
+    make_docs
+    # now assemble the release tar
     ./rebar3 as "$PROFILE" tar
     assert_no_compile_time_only_deps
 }

rebar.config.erl

@@ -156,15 +156,13 @@ profiles_ce() ->
             {erl_opts, prod_compile_opts(ce, Vsn)},
             {relx, relx(Vsn, cloud, bin, ce)},
             {overrides, prod_overrides()},
-            {project_app_dirs, project_app_dirs(ce)},
+            {project_app_dirs, project_app_dirs(ce)}
-            {post_hooks, [{compile, "bash build emqx doc"}]}
         ]},
         {'emqx-pkg', [
             {erl_opts, prod_compile_opts(ce, Vsn)},
             {relx, relx(Vsn, cloud, pkg, ce)},
             {overrides, prod_overrides()},
-            {project_app_dirs, project_app_dirs(ce)},
+            {project_app_dirs, project_app_dirs(ce)}
-            {post_hooks, [{compile, "bash build emqx-pkg doc"}]}
         ]}
     ].
 
@@ -175,15 +173,13 @@ profiles_ee() ->
             {erl_opts, prod_compile_opts(ee, Vsn)},
             {relx, relx(Vsn, cloud, bin, ee)},
             {overrides, prod_overrides()},
-            {project_app_dirs, project_app_dirs(ee)},
+            {project_app_dirs, project_app_dirs(ee)}
-            {post_hooks, [{compile, "bash build emqx-enterprise doc"}]}
         ]},
         {'emqx-enterprise-pkg', [
             {erl_opts, prod_compile_opts(ee, Vsn)},
             {relx, relx(Vsn, cloud, pkg, ee)},
             {overrides, prod_overrides()},
-            {project_app_dirs, project_app_dirs(ee)},
+            {project_app_dirs, project_app_dirs(ee)}
-            {post_hooks, [{compile, "bash build emqx-enterprise-pkg doc"}]}
         ]}
     ].
 
@@ -394,8 +390,8 @@ etc_overlay(ReleaseType, Edition) ->
     [
         {mkdir, "etc/"},
         {copy, "{{base_dir}}/lib/emqx/etc/certs", "etc/"},
-        {copy, "{{base_dir}}/lib/emqx_dashboard/etc/emqx-en.conf.example", "etc/"},
+        {copy, "apps/emqx_dashboard/priv/www/static/emqx-en.conf.example", "etc/"},
-        {copy, "{{base_dir}}/lib/emqx_dashboard/etc/emqx-zh.conf.example", "etc/"}
+        {copy, "apps/emqx_dashboard/priv/www/static/emqx-zh.conf.example", "etc/"}
     ] ++
         lists:map(
             fun