Adopt ExDoc & Move Documentation In-Tree

.gitignore

@@ -25,3 +25,4 @@ env
 
 # hex_core artifact
 apps/rebar/src/vendored/r3_safe_erl_term.erl
+apps/rebar/doc

apps/rebar/src/cth_fail_fast.erl

@@ -1,4 +1,5 @@
 -module(cth_fail_fast).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/cth_retry.erl

@@ -1,4 +1,5 @@
 -module(cth_retry).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/rebar_agent.erl

@@ -290,9 +290,9 @@ reload_modules(Modules0) ->
     Modules = [M || M <- Modules0, is_changed(M)],
     reload_modules(Modules, erlang:function_exported(code, prepare_loading, 1)).
 
-%% @spec is_changed(atom()) -> boolean()
 %% @doc true if the loaded module is a beam with a vsn attribute
 %%      and does not match the on-disk beam file, returns false otherwise.
+-spec is_changed(atom()) -> boolean().
 is_changed(M) ->
     try
         module_vsn(M:module_info(attributes)) =/= module_vsn(code:get_object_code(M))

apps/rebar/src/rebar_file_utils.erl

@@ -86,7 +86,7 @@ consult_config(State, Filename) ->
     consult_config_terms(State, Config).
 
 %% @doc Reads a config file via consult_env_config/2 if the file name has
-%% the suffix `.src`, and with consult_config/2 otherwise
+%% the suffix `.src', and with consult_config/2 otherwise
 -spec consult_any_config(rebar_state:t(), file:filename()) -> [[tuple()]].
 consult_any_config(State, Filename) ->
     case is_src_config(Filename) of

doc.config

@@ -0,0 +1,18 @@
+%% ./bootstrap
+%% REBAR_CONFIG=doc.config ./rebar3 ex_doc
+
+{project_plugins, [
+    {rebar3_ex_doc, "0.2.30"},
+    {rebar3_hex, "7.0.11"}
+]}.
+
+{hex, [{doc, #{provider => ex_doc}}]}.
+{ex_doc, [
+    {source_url, ~"https://example.com"},
+    {extras, [
+        ~"README.md",
+        ~"LICENSE",
+        ~"CONTRIBUTING.md"
+    ]},
+    {main, ~"readme"}
+]}.

doc.config.script

@@ -0,0 +1,34 @@
+case filelib:is_dir("rebar3.org") of
+    true ->
+        ok;
+    false ->
+        erlang:error("""
+        This demo requires that you clone the rebar3.org repository from GitHub
+        so that we can bundle the documentation together.
+
+            git clone https://github.com/tsloughter/rebar3.org.git
+        """)
+end,
+
+GetRebar3OrgFiles = fun() ->
+    Files = filelib:wildcard("rebar3.org/content/en/docs/**/*.md"),
+    lists:filter(fun(X) -> nomatch =:= re:run(X, "_index", [{capture, none}]) end, Files)
+end,
+
+FixHeader = fun(File) ->
+    io:format("Processing ~p~n", [File]),
+    {ok, Content} = file:read_file(File),
+    NewContent = re:replace(Content, "^---$\n+title: \"(?<title>[^\"]*)\"$.*^---$", "# \\1", [unicode, dotall, anchored, multiline]),
+    file:write_file(File, NewContent),
+    File
+end,
+
+MdFiles = GetRebar3OrgFiles(),
+MdFiles = lists:map(FixHeader, MdFiles),
+
+ExDoc = proplists:get_value(ex_doc, CONFIG),
+Extras = proplists:get_value(extras, ExDoc),
+Extras2 = Extras ++ MdFiles,
+ExDoc2 = lists:keystore(extras, 1, ExDoc, {extras, Extras2}),
+CONFIG2 = lists:keystore(ex_doc, 1, CONFIG, {ex_doc, ExDoc2}),
+CONFIG2.