Skip to content

Adopt ExDoc & Move Documentation In-Tree #2973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Adopt ExDoc & Move Documentation In-Tree #2973

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d80a5a3
let's try out exdoc
jessestimpson Sep 27, 2025
6d71337
Include rebar3.org docs
jessestimpson Sep 28, 2025
f68fcf6
Add docs from rebar3.org, reworked for ExDoc
jessestimpson Oct 5, 2025
987d920
Hack in support for groups_for_extras
jessestimpson Oct 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ env

# hex_core artifact
apps/rebar/src/vendored/r3_safe_erl_term.erl
apps/rebar/doc
1 change: 1 addition & 0 deletions apps/rebar/src/cth_fail_fast.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
-module(cth_fail_fast).
-moduledoc false.

%% Callbacks
-export([id/1]).
Expand Down
1 change: 1 addition & 0 deletions apps/rebar/src/cth_retry.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
-module(cth_retry).
-moduledoc false.

%% Callbacks
-export([id/1]).
Expand Down
2 changes: 1 addition & 1 deletion apps/rebar/src/rebar_agent.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
2 changes: 1 addition & 1 deletion apps/rebar/src/rebar_file_utils.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
18 changes: 18 additions & 0 deletions doc.config
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
%% ./bootstrap
%% REBAR_CONFIG=doc.config ./rebar3 ex_doc
Copy link
Collaborator

@ferd ferd Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This works and I'm not opposed to it. I think this method omits the rest of the Rebar3 config when working on the project, which may drop some settings. Was this on purpose because they might clash?

If it wasn't on purpose, then one option here would have been to use profiles for this whole section within the default rebar.config file, and then allow calling ./rebar3 as docs ex_doc. This would require unscripting the stuff in doc.config.script though, which would be way too much work for a demo I imagine, but might be worth it in the end if we go for full support.

Copy link
Contributor Author

@jessestimpson jessestimpson Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did it with doc.config[.script] on purpose for the first draft to demonstrate the blast radius of the change. Specifically, that the ex_doc config should be expected to have no impact on the rest of the project, to alleviate concerns about circular dependencies. I think we're on the same page here, so this is no longer a goal for the PR. 👍

I can continue the effort by exploring what it looks like in a merged rebar.config and without the script. However, without the script I think this will mean listing all markdown files explicitly in the rebar.config. I'll make it so and we can see how unmanageable that list looks. I don't mind doing multiple iterations to get it right.

Copy link
Collaborator

@ferd ferd Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I don't mind the file being distinct, the main concern is whether we'll require some duplication of config file values at some point. If we can survive without it, that's not a big deal.


{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"
Copy link
Collaborator

@ferd ferd Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sigil usage is generally supported starting in OTP-27, which means it is not necessarily usable for OTP-26, which is still currently supported.

Copy link
Contributor Author

@jessestimpson jessestimpson Sep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, good point. I will make this change

]},
{main, ~"readme"}
]}.
34 changes: 34 additions & 0 deletions doc.config.script
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading