From 5c52c2fdc75e3ec242c227fd7349259fefc3ad0d Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 21:28:53 +0200 Subject: [PATCH 01/20] Bring Rebar3 provider back --- src/rebar3_docsh_prv.erl | 86 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 src/rebar3_docsh_prv.erl diff --git a/src/rebar3_docsh_prv.erl b/src/rebar3_docsh_prv.erl new file mode 100644 index 0000000..527e35b --- /dev/null +++ b/src/rebar3_docsh_prv.erl @@ -0,0 +1,86 @@ +-module('rebar3_docsh_prv'). + +-export([init/1, do/1, format_error/1]). + +-define(PROVIDER, compile). +-define(DEPS, [{default, compile}]). +-define(SHORT_DESC, "Store modules' documentation in Docs chunks according to EEP-48"). +-define(DESC, "Store modules' documentation in Docs chunks according to EEP-48.\n" + "This exposes Erlang module documentation to Elixir and other BEAM languages.\n" + "Use https://github.com/erszcz/docsh to access your docs in an Erlang shell.\n"). + +%% =================================================================== +%% Public API +%% =================================================================== + +-spec init(rebar_state:t()) -> {ok, rebar_state:t()}. +init(State) -> + POpts = [ + {name, ?PROVIDER}, % The 'user friendly' name of the task + {namespace, docsh}, + {module, ?MODULE}, % The module implementation of the task + {bare, true}, % The task can be run by the user, always true + {deps, ?DEPS}, % The list of dependencies + {opts, []}, % list of options understood by the plugin + {short_desc, ?SHORT_DESC}, + {desc, ?DESC} + ], + Provider = providers:create(POpts), + {ok, rebar_state:add_provider(State, Provider)}. + +-spec do(rebar_state:t()) -> {ok, rebar_state:t()} | {error, string()}. +do(State) -> + Apps = case rebar_state:current_app(State) of + undefined -> + rebar_state:project_apps(State); + AppInfo -> + [AppInfo] + end, + [ process_app(State, App) || App <- Apps ], + {ok, State}. + +-spec format_error(any()) -> iolist(). +format_error(Reason) -> + docsh_lib:format_error(Reason). + +%% =================================================================== +%% Helpers +%% =================================================================== + +-spec process_app(rebar_state:t(), rebar_app_info:t()) -> ok. +process_app(State, App) -> + BEAMs = app_beam_files(App), + [ process_beam(State, B) || B <- BEAMs ]. + +-spec app_beam_files(rebar_app_info:t()) -> [file:filename()]. +app_beam_files(App) -> + EbinDir = rebar_app_info:ebin_dir(App), + filelib:wildcard(filename:join([EbinDir, "*.beam"])). + +-spec process_beam(rebar_state:t(), file:filename()) -> ok. +process_beam(_State, BeamFile) -> + try + {ok, B} = docsh_beam:from_beam_file(BeamFile), + {ok, Docs, Warnings} = docsh_lib:make_docs(B), + print_warnings(docsh_beam:name(B), Warnings), + DocsChunk = make_docs_chunk(Docs), + {ok, NewBeam} = add_chunks(BeamFile, [DocsChunk]), + ok = file:write_file(BeamFile, NewBeam) + catch + _:R -> + io:format(standard_error, + "unexpected error: ~p\n" + "stacktrace: ~p\n", + [R, erlang:get_stacktrace()]), + ok + end. + +print_warnings(Name, Warnings) -> + [ docsh_lib:print("~s", [docsh_lib:format_error({W, Name})]) || W <- Warnings ]. + +make_docs_chunk(Docs) -> + {"Docs", term_to_binary(Docs, [compressed])}. + +add_chunks(BeamFile, NewChunks) -> + {ok, _, OldChunks} = beam_lib:all_chunks(BeamFile), + {ok, _NewBEAM} = beam_lib:build_module(OldChunks ++ NewChunks). From 8f733e0e8f093271ef549f1a5cd9246c597a9086 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 21:44:46 +0200 Subject: [PATCH 02/20] Disambiguate between function/type when preparing a doc item signature --- src/docsh_docs_v1.erl | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/src/docsh_docs_v1.erl b/src/docsh_docs_v1.erl index fd8c240..64a81fd 100644 --- a/src/docsh_docs_v1.erl +++ b/src/docsh_docs_v1.erl @@ -145,7 +145,7 @@ step(_ModuleInfo, {Name, Arity}, Info0, { #docs_v1{} = DocsV1, DocsMap }) -> KNA = {Kind, Name, Arity}, Entry = { {Kind, Name, Arity}, erl_anno:new({0, 1}), - signature(Name, Arity, Info), + signature(Kind, Name, Arity, Info), #{<<"en">> => description(Name, Arity, Info)}, #{} }, {DocsV1, DocsMap#{KNA => Entry}}. @@ -165,19 +165,18 @@ infer_item_kind(Info) -> _ -> type end. -signature(Name, Arity, Info) -> - case {docsh_lib:get(spec, Info, not_found), - docsh_lib:get(type, Info, not_found)} of - {not_found, not_found} -> +signature(Kind, Name, Arity, Info) -> + InfoKey = case Kind of + function -> spec; + type -> type + end, + case docsh_lib:get(InfoKey, Info, not_found) of + not_found -> SName = atom_to_list(Name), SArity = integer_to_list(Arity), [iolist_to_binary([SName, "/", SArity])]; - {Spec, not_found} -> - [Spec]; - {not_found, Type} -> - [Type]; - {_Spec, _Type} -> - error(spec_and_type_present, [Name, Arity, Info]) + InfoItem -> + [InfoItem] end. module_doc(ModuleInfo) -> From b41274f35d23c73322ea651f7a4dd5e3b5d419e1 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 21:44:57 +0200 Subject: [PATCH 03/20] Fix unused vars --- src/docsh_docs_v1.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docsh_docs_v1.erl b/src/docsh_docs_v1.erl index 64a81fd..be4fde7 100644 --- a/src/docsh_docs_v1.erl +++ b/src/docsh_docs_v1.erl @@ -94,7 +94,7 @@ format_functions(Mod, Items, Kinds, Lang) -> DocIfRequested <- [ "" ++ [ ["\n", format_maybe_doc(MaybeDoc, Lang)] || lists:member(doc, Kinds) ] ] ]). -format_types(Mod, Items, Lang) -> +format_types(_Mod, Items, _Lang) -> ?il2b([ [?il2b([Signature])] || {{_, _Name, _Arity}, _, Signature, _, _Metadata} <- Items ]). From 213e2a21b1d403228053f4840eff688d3d45ed8a Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 21:45:14 +0200 Subject: [PATCH 04/20] Return a more descriptive error --- src/docsh_lib.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docsh_lib.erl b/src/docsh_lib.erl index 1a1d3b1..f9f83f1 100644 --- a/src/docsh_lib.erl +++ b/src/docsh_lib.erl @@ -256,7 +256,7 @@ make_docs(Beam) -> andalso error(docs_present, [BEAMFile]), case {docsh_beam:abstract_code(Beam), docsh_beam:source_file(Beam)} of {false, false} -> - error(no_debug_info_no_src, [BEAMFile]); + error({no_debug_info_no_src, BEAMFile}, [BEAMFile]); {_, false} -> {ok, do_make_docs(Beam), [no_src]}; {false, _} -> From dfa6b36d427e46958c9089bac2fc9c45fe5a7d23 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 22:30:45 +0200 Subject: [PATCH 05/20] Extract check_precondition/2 to docsh_helpers --- test/docsh_helpers.erl | 8 ++++++++ test/install_SUITE.erl | 15 ++++----------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/test/docsh_helpers.erl b/test/docsh_helpers.erl index 28af247..6b7700f 100644 --- a/test/docsh_helpers.erl +++ b/test/docsh_helpers.erl @@ -28,3 +28,11 @@ sh_log(Command, Code, Result) -> "code : ~p\n" "result : ~ts", [Command, Code, Result]). + +check_precondition({Name, P}, Config) -> + try + P(Config), + ok + catch _:Reason -> + ct:fail("~ts failed: ~p", [Name, Reason]) + end. diff --git a/test/install_SUITE.erl b/test/install_SUITE.erl index c9a0c6c..86922ee 100644 --- a/test/install_SUITE.erl +++ b/test/install_SUITE.erl @@ -1,7 +1,8 @@ -module(install_SUITE). -compile(export_all). --import(docsh_helpers, [sh/1]). +-import(docsh_helpers, [check_precondition/2, + sh/1]). -include_lib("common_test/include/ct.hrl"). -include_lib("eunit/include/eunit.hrl"). @@ -15,10 +16,10 @@ all() -> [docker_linux]. init_per_suite(Config) -> - [ check(P, Config) || P <- prerequisites() ], + [ check_precondition(P, Config) || P <- preconditions() ], Config. -prerequisites() -> +preconditions() -> [ { "docker in $PATH", fun (_Config) -> {_, _, <<"Docker", _/bytes>>} = sh("docker -v") end }, { "git in $PATH", fun (_) -> {_, _, <<"usage: git", _/bytes>>} = sh("git --help") end } @@ -72,14 +73,6 @@ docker_linux(_) -> %% Helpers %% -check({Name, P}, Config) -> - try - P(Config), - ok - catch _:Reason -> - ct:fail("~ts failed: ~p", [Name, Reason]) - end. - container_name(Prefix) -> RawRandomBytes = crypto:strong_rand_bytes(9), Base64 = base64:encode(RawRandomBytes), From 91c6f5ccb22d72925a55c7995f2f8a07ef6fffa0 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Sat, 14 Jul 2018 22:32:27 +0200 Subject: [PATCH 06/20] Stub rebar3_docsh_prv_SUITE --- test/rebar3_docsh_prv_SUITE.erl | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 test/rebar3_docsh_prv_SUITE.erl diff --git a/test/rebar3_docsh_prv_SUITE.erl b/test/rebar3_docsh_prv_SUITE.erl new file mode 100644 index 0000000..b48276c --- /dev/null +++ b/test/rebar3_docsh_prv_SUITE.erl @@ -0,0 +1,21 @@ +-module(rebar3_docsh_prv_SUITE). +-compile([export_all]). + +-import(docsh_helpers, [check_precondition/2, + sh/1]). + +init_per_suite(Config) -> + [ check_precondition(P, Config) || P <- preconditions() ], + Config. + +preconditions() -> + [ + { "git in $PATH", fun (_) -> {_, _, <<"usage: git", _/bytes>>} = sh("git --help") end } + ]. + +end_per_suite(_Config) -> + ok. + +%% +%% Helpers +%% From b808663b53f97c995835e5404b55b05fe431e9fe Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Mon, 16 Jul 2018 11:28:14 +0200 Subject: [PATCH 07/20] Declare provider behaviour --- src/rebar3_docsh_prv.erl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/rebar3_docsh_prv.erl b/src/rebar3_docsh_prv.erl index 527e35b..3d12847 100644 --- a/src/rebar3_docsh_prv.erl +++ b/src/rebar3_docsh_prv.erl @@ -1,6 +1,9 @@ -module('rebar3_docsh_prv'). --export([init/1, do/1, format_error/1]). +-behaviour(provider). +-export([init/1, + do/1, + format_error/1]). -define(PROVIDER, compile). -define(DEPS, [{default, compile}]). From 72cf2d01c8389c93ff384eb53e432d353640d809 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Mon, 16 Jul 2018 11:31:54 +0200 Subject: [PATCH 08/20] Rename: rebar3_docsh_prv -> rebar3_prv_docsh --- src/{rebar3_docsh_prv.erl => rebar3_prv_docsh.erl} | 2 +- ...sh_prv_SUITE.erl => rebar3_prv_docsh_SUITE.erl} | 14 +++++++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) rename src/{rebar3_docsh_prv.erl => rebar3_prv_docsh.erl} (99%) rename test/{rebar3_docsh_prv_SUITE.erl => rebar3_prv_docsh_SUITE.erl} (75%) diff --git a/src/rebar3_docsh_prv.erl b/src/rebar3_prv_docsh.erl similarity index 99% rename from src/rebar3_docsh_prv.erl rename to src/rebar3_prv_docsh.erl index 3d12847..58e38a1 100644 --- a/src/rebar3_docsh_prv.erl +++ b/src/rebar3_prv_docsh.erl @@ -1,4 +1,4 @@ --module('rebar3_docsh_prv'). +-module('rebar3_prv_docsh'). -behaviour(provider). -export([init/1, diff --git a/test/rebar3_docsh_prv_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl similarity index 75% rename from test/rebar3_docsh_prv_SUITE.erl rename to test/rebar3_prv_docsh_SUITE.erl index b48276c..d1408a9 100644 --- a/test/rebar3_docsh_prv_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -1,4 +1,4 @@ --module(rebar3_docsh_prv_SUITE). +-module(rebar3_prv_docsh_SUITE). -compile([export_all]). -import(docsh_helpers, [check_precondition/2, @@ -16,6 +16,18 @@ preconditions() -> end_per_suite(_Config) -> ok. +%% +%% Config +%% + +recon_repo() -> + "https://github.com/erszcz/recon". + +%% +%% Tests +%% + + %% %% Helpers %% From 77b5994e2e06f9cbbe7de67f27a9152ba8bd9a07 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Wed, 18 Jul 2018 18:29:37 +0200 Subject: [PATCH 09/20] Test that rebar3_prv_docsh_compiles_in_the_docs_chunk --- test/rebar3_prv_docsh_SUITE.erl | 46 +++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index d1408a9..213dac1 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -16,6 +16,9 @@ preconditions() -> end_per_suite(_Config) -> ok. +all() -> + [rebar3_prv_docsh_compiles_in_the_docs_chunk]. + %% %% Config %% @@ -27,7 +30,50 @@ recon_repo() -> %% Tests %% +rebar3_prv_docsh_compiles_in_the_docs_chunk(_) -> + put(sh_log, true), + %% given + AppName = "recon", + sh(clone(recon_repo())), + %% when + {ok, ProjectDir} = compile(AppName), + %% then all modules have the "Docs" chunk + {ok, Modules} = app_modules(AppName, ProjectDir), + ModuleDocs = [ begin + %% Not using docsh here so we're 100% sure it doesn't make docs_v1 on demand. + BeamFile = code:which(M), + {ok, {_Mod, [{"Docs", BDocs}]}} = beam_lib:chunks(BeamFile, ["Docs"]), + {ok, erlang:binary_to_term(BDocs)} + end || M <- Modules ], + ct:pal("~s module docs:\n~p", [AppName, ModuleDocs]), + [ok, ok, ok, ok] = [ element(1, MD) || MD <- ModuleDocs ], + ok. %% %% Helpers %% + +quote(Text) -> + ["\"", Text, "\""]. + +clone(Repo) -> + ["git clone ", Repo]. + +compile(Project) -> + {ok, Dir} = file:get_cwd(), + ProjectDir = filename:join([Dir, Project]), + try + ok = file:set_cwd(ProjectDir), + rebar_agent:start_link(rebar_state:new()), + r3:compile(), + {ok, ProjectDir} + after + ok = file:set_cwd(Dir) + end. + +app_modules(AppName, ProjectDir) -> + AppFile = filename:join([ProjectDir, "_build", "default", "lib", AppName, "ebin", AppName ++ ".app"]), + {ok, AppSpec} = file:consult(AppFile), + [{application, recon, AppProps}] = AppSpec, + {modules, Modules} = lists:keyfind(modules, 1, AppProps), + {ok, Modules}. From 3575c8742142feec8e3cf1cbca16ec7e1634b76e Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 12:00:34 +0200 Subject: [PATCH 10/20] Let it crash --- src/rebar3_prv_docsh.erl | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/src/rebar3_prv_docsh.erl b/src/rebar3_prv_docsh.erl index 58e38a1..c42acbc 100644 --- a/src/rebar3_prv_docsh.erl +++ b/src/rebar3_prv_docsh.erl @@ -62,21 +62,12 @@ app_beam_files(App) -> -spec process_beam(rebar_state:t(), file:filename()) -> ok. process_beam(_State, BeamFile) -> - try - {ok, B} = docsh_beam:from_beam_file(BeamFile), - {ok, Docs, Warnings} = docsh_lib:make_docs(B), - print_warnings(docsh_beam:name(B), Warnings), - DocsChunk = make_docs_chunk(Docs), - {ok, NewBeam} = add_chunks(BeamFile, [DocsChunk]), - ok = file:write_file(BeamFile, NewBeam) - catch - _:R -> - io:format(standard_error, - "unexpected error: ~p\n" - "stacktrace: ~p\n", - [R, erlang:get_stacktrace()]), - ok - end. + {ok, B} = docsh_beam:from_beam_file(BeamFile), + {ok, Docs, Warnings} = docsh_lib:make_docs(B), + print_warnings(docsh_beam:name(B), Warnings), + DocsChunk = make_docs_chunk(Docs), + {ok, NewBeam} = add_chunks(BeamFile, [DocsChunk]), + ok = file:write_file(BeamFile, NewBeam). print_warnings(Name, Warnings) -> [ docsh_lib:print("~s", [docsh_lib:format_error({W, Name})]) || W <- Warnings ]. From f36753240b8e559de9f8e440af7b2f69016d080d Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 12:52:20 +0200 Subject: [PATCH 11/20] Test that rebar3_prv_docsh_handles_present_docs_chunk without crashing --- test/rebar3_prv_docsh_SUITE.erl | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index 213dac1..d514847 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -17,7 +17,14 @@ end_per_suite(_Config) -> ok. all() -> - [rebar3_prv_docsh_compiles_in_the_docs_chunk]. + [{group, main}]. + +groups() -> + [{main, [sequence], + [ + rebar3_prv_docsh_compiles_in_the_docs_chunk, + rebar3_prv_docsh_handles_present_docs_chunk + ]}]. %% %% Config @@ -49,6 +56,13 @@ rebar3_prv_docsh_compiles_in_the_docs_chunk(_) -> [ok, ok, ok, ok] = [ element(1, MD) || MD <- ModuleDocs ], ok. +rebar3_prv_docsh_handles_present_docs_chunk(_) -> + %% given the previously cloned repo (these tests run in sequence!) + AppName = "recon", + %% when compiling / then we should exit without `docs_present` error + {ok, _ProjectDir} = compile(AppName), + ok. + %% %% Helpers %% @@ -65,7 +79,7 @@ compile(Project) -> try ok = file:set_cwd(ProjectDir), rebar_agent:start_link(rebar_state:new()), - r3:compile(), + ok = r3:compile(), {ok, ProjectDir} after ok = file:set_cwd(Dir) From 92da0a0ee9b42dd1743628a45238eb6f4795e188 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:03:14 +0200 Subject: [PATCH 12/20] Don't issue warnings for export_all option --- test/rebar3_prv_docsh_SUITE.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index d514847..e53a9c4 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -1,5 +1,5 @@ -module(rebar3_prv_docsh_SUITE). --compile([export_all]). +-compile([export_all, nowarn_export_all]). -import(docsh_helpers, [check_precondition/2, sh/1]). From adcda3025a450ac05649de482b3f8df53ad43d81 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:19:59 +0200 Subject: [PATCH 13/20] Control on-demand Docs building via an application option --- src/docsh_lib.erl | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/src/docsh_lib.erl b/src/docsh_lib.erl index f9f83f1..3b377c0 100644 --- a/src/docsh_lib.erl +++ b/src/docsh_lib.erl @@ -229,16 +229,9 @@ get_docs(M) -> case docsh_beam:from_loaded_module(M) of {error, _} = E -> E; {ok, B} -> - case do_get_docs(B) of - {ok, Docs} -> - {ok, Docs}; - {error, _} -> - {ok, Docs, Warnings} = make_docs(B), - [ print("~s", [docsh_lib:format_error({W, docsh_beam:name(B)})]) || W <- Warnings ], - %% TODO: enable cache at some point - %cache_docs(B, Docs), - {ok, Docs} - end + MakeDocs = application:get_env(docsh, compile_on_demand, compile_if_missing), + AvailableDocs = do_get_docs(B), + dispatch_docs_extraction(B, MakeDocs, AvailableDocs) end. do_get_docs(B) -> @@ -248,6 +241,24 @@ do_get_docs(B) -> {error, R} end. +dispatch_docs_extraction(B, never, AvailableDocs) -> + %% just for troubleshooting + {ok, [B, never, AvailableDocs]}; +dispatch_docs_extraction(_, compile_if_missing, {ok, Docs}) -> + {ok, Docs}; +dispatch_docs_extraction(B, compile_if_missing, {error, _} = Err) -> + %% TODO: log Reason? + dispatch_docs_extraction(B, always, Err); +dispatch_docs_extraction(B, always, _) -> + dispatch_docs_extraction_(B). + +dispatch_docs_extraction_(B) -> + {ok, Docs, Warnings} = make_docs(B), + [ print("~s", [docsh_lib:format_error({W, docsh_beam:name(B)})]) || W <- Warnings ], + %% TODO: enable cache at some point + %cache_docs(B, Docs), + {ok, Docs}. + -spec make_docs(docsh_beam:t()) -> {ok, docsh_format:t(), [Warning]} when Warning :: no_debug_info | no_src. make_docs(Beam) -> From f4c003f645d70ddd5939db7a68710144d2d01b4c Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:27:39 +0200 Subject: [PATCH 14/20] Extract current_git_commit/0 to docsh_helpers --- test/docsh_helpers.erl | 9 ++++++++- test/install_SUITE.erl | 10 ++-------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/test/docsh_helpers.erl b/test/docsh_helpers.erl index 6b7700f..bcc3a15 100644 --- a/test/docsh_helpers.erl +++ b/test/docsh_helpers.erl @@ -1,5 +1,5 @@ -module(docsh_helpers). --compile([export_all]). +-compile([export_all, nowarn_export_all]). -define(b2l(B), binary_to_list(B)). -define(il2b(IL), iolist_to_binary(IL)). @@ -36,3 +36,10 @@ check_precondition({Name, P}, Config) -> catch _:Reason -> ct:fail("~ts failed: ~p", [Name, Reason]) end. + +current_git_commit() -> + case os:getenv("TRAVIS_PULL_REQUEST_SHA") of + false -> {_, _, R} = sh("git rev-parse HEAD"), + R; + Commit -> Commit + end. diff --git a/test/install_SUITE.erl b/test/install_SUITE.erl index 86922ee..b7c7bed 100644 --- a/test/install_SUITE.erl +++ b/test/install_SUITE.erl @@ -1,7 +1,8 @@ -module(install_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -import(docsh_helpers, [check_precondition/2, + current_git_commit/0, sh/1]). -include_lib("common_test/include/ct.hrl"). @@ -114,13 +115,6 @@ is_container_running(Name) -> true catch _:_ -> false end. -current_git_commit() -> - case os:getenv("TRAVIS_PULL_REQUEST_SHA") of - false -> {_, _, R} = sh("git rev-parse HEAD"), - R; - Commit -> Commit - end. - clone(Repo) -> ["git clone ", Repo]. From 6531962004ba88a19e1dde431844e37b8f2a50a4 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:40:42 +0200 Subject: [PATCH 15/20] Make rebar3_prv_docsh_SUITE always test the current docsh commit --- test/rebar3_prv_docsh_SUITE.erl | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index e53a9c4..eb342d5 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -2,6 +2,7 @@ -compile([export_all, nowarn_export_all]). -import(docsh_helpers, [check_precondition/2, + current_git_commit/0, sh/1]). init_per_suite(Config) -> @@ -30,6 +31,9 @@ groups() -> %% Config %% +docsh_repo() -> + "https://github.com/erszcz/docsh". + recon_repo() -> "https://github.com/erszcz/recon". @@ -42,6 +46,7 @@ rebar3_prv_docsh_compiles_in_the_docs_chunk(_) -> %% given AppName = "recon", sh(clone(recon_repo())), + get_docsh_plugin(AppName, docsh_repo(), current_git_commit()), %% when {ok, ProjectDir} = compile(AppName), %% then all modules have the "Docs" chunk @@ -73,6 +78,9 @@ quote(Text) -> clone(Repo) -> ["git clone ", Repo]. +clone(Repo, Target) -> + ["git clone ", Repo, " ", Target]. + compile(Project) -> {ok, Dir} = file:get_cwd(), ProjectDir = filename:join([Dir, Project]), @@ -85,6 +93,12 @@ compile(Project) -> ok = file:set_cwd(Dir) end. +get_docsh_plugin(AppName, DocshRepo, Ref) -> + DocshPlugin = filename:join([AppName, "_checkouts", "rebar3_prv_docsh"]), + ok = filelib:ensure_dir(DocshPlugin), + sh(clone(DocshRepo, DocshPlugin)), + sh("cd " ++ DocshPlugin ++ " && git checkout " ++ Ref). + app_modules(AppName, ProjectDir) -> AppFile = filename:join([ProjectDir, "_build", "default", "lib", AppName, "ebin", AppName ++ ".app"]), {ok, AppSpec} = file:consult(AppFile), From 3d13de09440bd7359169176cccef3b5841feafff Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:44:35 +0200 Subject: [PATCH 16/20] Remove dead code line --- test/rebar3_prv_docsh_SUITE.erl | 1 - 1 file changed, 1 deletion(-) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index eb342d5..046796a 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -58,7 +58,6 @@ rebar3_prv_docsh_compiles_in_the_docs_chunk(_) -> {ok, erlang:binary_to_term(BDocs)} end || M <- Modules ], ct:pal("~s module docs:\n~p", [AppName, ModuleDocs]), - [ok, ok, ok, ok] = [ element(1, MD) || MD <- ModuleDocs ], ok. rebar3_prv_docsh_handles_present_docs_chunk(_) -> From a26038b47e0fc205b35b7d99ea808b1d4a7f743b Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:52:10 +0200 Subject: [PATCH 17/20] rebar3_prv_docsh: Don't compile Docs if they're present --- src/rebar3_prv_docsh.erl | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/src/rebar3_prv_docsh.erl b/src/rebar3_prv_docsh.erl index c42acbc..787fdeb 100644 --- a/src/rebar3_prv_docsh.erl +++ b/src/rebar3_prv_docsh.erl @@ -62,12 +62,17 @@ app_beam_files(App) -> -spec process_beam(rebar_state:t(), file:filename()) -> ok. process_beam(_State, BeamFile) -> - {ok, B} = docsh_beam:from_beam_file(BeamFile), - {ok, Docs, Warnings} = docsh_lib:make_docs(B), - print_warnings(docsh_beam:name(B), Warnings), - DocsChunk = make_docs_chunk(Docs), - {ok, NewBeam} = add_chunks(BeamFile, [DocsChunk]), - ok = file:write_file(BeamFile, NewBeam). + case docsh_lib:has_docs(BeamFile) of + true -> + ok; + false -> + {ok, B} = docsh_beam:from_beam_file(BeamFile), + {ok, Docs, Warnings} = docsh_lib:make_docs(B), + print_warnings(docsh_beam:name(B), Warnings), + DocsChunk = make_docs_chunk(Docs), + {ok, NewBeam} = add_chunks(BeamFile, [DocsChunk]), + ok = file:write_file(BeamFile, NewBeam) + end. print_warnings(Name, Warnings) -> [ docsh_lib:print("~s", [docsh_lib:format_error({W, Name})]) || W <- Warnings ]. From 49cfd7dcab533ce46b26f0e5c8a13b3f3e8bf8ab Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:53:57 +0200 Subject: [PATCH 18/20] Comment out a debugging printout --- test/rebar3_prv_docsh_SUITE.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index 046796a..4a2f904 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -57,7 +57,7 @@ rebar3_prv_docsh_compiles_in_the_docs_chunk(_) -> {ok, {_Mod, [{"Docs", BDocs}]}} = beam_lib:chunks(BeamFile, ["Docs"]), {ok, erlang:binary_to_term(BDocs)} end || M <- Modules ], - ct:pal("~s module docs:\n~p", [AppName, ModuleDocs]), + %ct:pal("~s module docs:\n~p", [AppName, ModuleDocs]), ok. rebar3_prv_docsh_handles_present_docs_chunk(_) -> From 14bab26d07dc2d8b0e38a7ec7456d904fc1efa23 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 13:56:46 +0200 Subject: [PATCH 19/20] Don't warn about export_all where applicable --- src/docsh_tracer.erl | 3 +-- test/completeness_SUITE.erl | 2 +- test/ct_helper.erl | 3 +-- test/docsh_SUITE.erl | 2 +- test/edoc_SUITE.erl | 2 +- test/proplists_eq_SUITE.erl | 2 +- test/syntax_SUITE.erl | 2 +- 7 files changed, 7 insertions(+), 9 deletions(-) diff --git a/src/docsh_tracer.erl b/src/docsh_tracer.erl index baeaa0d..966c371 100644 --- a/src/docsh_tracer.erl +++ b/src/docsh_tracer.erl @@ -1,6 +1,5 @@ -module(docsh_tracer). - --compile([export_all]). +-compile([export_all, nowarn_export_all]). -define(il2b, iolist_to_binary). diff --git a/test/completeness_SUITE.erl b/test/completeness_SUITE.erl index b6d4099..a8ec428 100644 --- a/test/completeness_SUITE.erl +++ b/test/completeness_SUITE.erl @@ -1,5 +1,5 @@ -module(completeness_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -import(docsh_helpers, [sh/2]). diff --git a/test/ct_helper.erl b/test/ct_helper.erl index 7e6c2ee..72159ef 100644 --- a/test/ct_helper.erl +++ b/test/ct_helper.erl @@ -1,6 +1,5 @@ -module(ct_helper). - --compile([export_all]). +-compile([export_all, nowarn_export_all]). %% @doc Like ct:get_config/1, but calls error/1 if Key is not found / undefined. %% This guarantees to fail fast if required config options are missing from diff --git a/test/docsh_SUITE.erl b/test/docsh_SUITE.erl index 99b8421..9faae24 100644 --- a/test/docsh_SUITE.erl +++ b/test/docsh_SUITE.erl @@ -1,5 +1,5 @@ -module(docsh_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -include_lib("common_test/include/ct.hrl"). -include_lib("eunit/include/eunit.hrl"). diff --git a/test/edoc_SUITE.erl b/test/edoc_SUITE.erl index b836206..ad83d4e 100644 --- a/test/edoc_SUITE.erl +++ b/test/edoc_SUITE.erl @@ -1,5 +1,5 @@ -module(edoc_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -include_lib("eunit/include/eunit.hrl"). -include("proplists_eq.hrl"). diff --git a/test/proplists_eq_SUITE.erl b/test/proplists_eq_SUITE.erl index 2ab657d..9dc65fe 100644 --- a/test/proplists_eq_SUITE.erl +++ b/test/proplists_eq_SUITE.erl @@ -1,5 +1,5 @@ -module(proplists_eq_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -include_lib("eunit/include/eunit.hrl"). diff --git a/test/syntax_SUITE.erl b/test/syntax_SUITE.erl index 79e05aa..6629095 100644 --- a/test/syntax_SUITE.erl +++ b/test/syntax_SUITE.erl @@ -1,5 +1,5 @@ -module(syntax_SUITE). --compile(export_all). +-compile([export_all, nowarn_export_all]). -include_lib("eunit/include/eunit.hrl"). -include("proplists_eq.hrl"). From 5113f54cb0cb3ba8fa611fbeadfaabc6a09f8ff6 Mon Sep 17 00:00:00 2001 From: Radek Szymczyszyn Date: Thu, 19 Jul 2018 14:03:03 +0200 Subject: [PATCH 20/20] Call explicitly defined rebar_agent:do/1 --- test/rebar3_prv_docsh_SUITE.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/rebar3_prv_docsh_SUITE.erl b/test/rebar3_prv_docsh_SUITE.erl index 4a2f904..3218685 100644 --- a/test/rebar3_prv_docsh_SUITE.erl +++ b/test/rebar3_prv_docsh_SUITE.erl @@ -86,7 +86,7 @@ compile(Project) -> try ok = file:set_cwd(ProjectDir), rebar_agent:start_link(rebar_state:new()), - ok = r3:compile(), + ok = rebar_agent:do(compile), {ok, ProjectDir} after ok = file:set_cwd(Dir)