before_closing_body_tag option

[MarkoMin]

Hi,

I just tried rebar3_ex_doc and I'd like to render mermaid graphs. I got it working by placing {before_closing_body_tag, fun my_mod:html/1} option. However, there are 2 problems with this approach:

1. Option is warned as "unknown", but it works (In docs it says that this should be reported as an issue)
2. As lamba functions are not valid in Erlang config files, is there a way to avoid MFA call? I don't want that function in my production code...

p.s. I'm open to contribution

[starbelly]

Agreed. We need to support this and with as little friction as possible. So, like you could have a module that's just for doing this kind of stuff, and have it excluded from your release, but that feels like friction. I'm asking about if supporting anon functions in rebar.config is even possible.

[MarkoMin]

It is not possible in rebar.config because it uses file:consult/1 to read config file, so this would throw an error. Luckily, rebar3_ex_doc support external configuration, so we can have {rebar3_ex_doc, "ex_doc.config.script"} entry in the rebar.config, but we need to call file:script/1 in rebar3_ex_doc, anonymous functions are legal in those files. I think this shouldn't even break the backward compatibility, but would add a really nice feature.

[starbelly]

I don't think anon functions in rebar.config are going to work, but I do have an idea that would be frictionless.

What about an option for in ex_doc config (within rebar.config) that looks something like :

 {before_closing_body_tag, %{html => "some bit of javascript code / css / whatever",
                                                  css => "bla bla bla",
                                                 ..
                                                 }}

Then rebar3_ex_doc can make an anon function using this data. I'm not sure exactly how we would dump this to config for ex doc, as I've only ever used mix.exs to accomplish this, so have to make sure dumping it to config at that point is doable.

Edit:

ex_doc uses file:consult/1 when reading in a config file that is not exs, so that would be a no go. But worth pointing out a temporary work around is indeed the new support for specifying a .exs config file.

[MarkoMin]

So, option 1 is to allow .exs config files and option 2 is to support before_closing_body_tag via map and then transform .config files to .exs? First one is easier, but I don't know how it gonna affect UX when developing in Erlang, it may be a turn off. Second one requires more work, but doesn't require any Elixir in Erlang projects. Is there any lib that transforms .config to .exs?

Also, option 3 is to just use some module which is excluded from compilation... Rebar3 runs ex_doc in docs profile, so I've included this module only when compiling in that profile, its one line in rebar.config. This works for me. Maybe it's not worth the effort, because IMO neither solution is very clean, so maybe we can just leave it as it is, add a paragraph about how to work with module included only when you're generating docs and disable the warning of "unknown opt".

[starbelly]

@MarkoMin Two PRs were done to ex_doc to facilitate this better.

https://github.com/elixir-lang/ex_doc/pull/1676

https://github.com/elixir-lang/ex_doc/pull/1670

Waiting for a new version of ex_doc to be cut, then a new version of this plugin will be released.

[starbelly]

Hey guys, this fell on the floor. v0.2.18 has been released with ex_doc v0.29.4. Let me know if you have issues ❤️