Update to allow generating documentation from OTP 27 on

[paulo-ferraz-oliveira]

Check what is required to have local documentation built from OTP 27 on.

Ref: https://erlangforums.com/t/erlang-otp-27-0-rc1-released/3300/14

Option: KERL_BUILD_DOCS=true

It is quite possible we need to slightly adjust kerl to temporarily install (or ask to install) ex_doc locally.

[garazdawi]

Since kerl already downloads things from the internet and that is the expected behaviour, I would also download ex_doc if the user provides KERL_BUILD_DOCS=true for an Erlang version after 26.

I've opened a pr that removes the warning about documentation not being able to be built. I could also add a command to otp_build that would download the correct ExDoc version so that kerl can use that.

[paulo-ferraz-oliveira]

I've opened a pr that removes the warning about documentation not being able to be built. I could also add a command to otp_build that would download the correct ExDoc version so that kerl can use that.

I've opened a erlang/otp#8129 that removes the warning about documentation not being able to be built. I could also add a command to otp_build that would download the correct ExDoc version so that kerl can use that.

That'd be perfect. Then we'd just add it to the path upon activate, since kerl already manipulates it. Thanks.

[garazdawi]

I've updated erlang/otp#8129 to now include ./otp_build download_ex_doc that downloads the correct ex_doc version from github and places it in "$ERL_TOP/bin/". The only thing you should have to do is call that before building the Erlang/OTP docs.

IMO if an Erlang application wants to use ExDoc they should download it separetly for their needs so that they get the right version, though I can see the appeal of it always being available when erlang is installed with kerl. Though if we go down that route, then rebar3 would also be a nice candidate for something to always we installed when using kerl.

[paulo-ferraz-oliveira]

then rebar3 would also be a nice candidate for something to always we installed when using kerl

I can understand that, but I don't know if it's comparable. From what I understand, from OTP 27 on you're unable to build the docs without ex_doc. Building the docs is somethink kerl already allows, so we'd be forfeiting some functionality.

Edit: upon re-reading your previous comments better, I believe you mentioned we shouldn't download the tool for anything other than building the docs. With that I'm 100%.

Otoh, I'd never consider it, but it could be nice to include rebar3 with an installation (though my hope is it one day makes it to Erlang itself, as proposed in the past 😆), why not? There's maybe obstacles or "there be dragons" I'm not foreseeing, though, but it would be possible.

@jadeallenx, thoughts on:

• documentation
• rebar3

?

Note: we could also propose, for example, if you're trying to build the docs and don't have ex_doc installed, that you do it yourself, with a warning, and point to the instructions you just mentioned, instead of doing it ourselves, but what would be our concern here? Security? or otherwise?

[garazdawi]

From what I understand, from OTP 27 on you're unable to build the docs without ex_doc. Building the docs is somethink kerl already allows, so we'd be forfeiting some functionality.

You cannot build the Erlang/OTP docs, but any docs written by the user of erlang can be built just as before.

So there is no reason to install ex_doc when installing erlang docs. However, you do need it build the docs. So I would download ex_doc as part of kerl build if asked to build docs, but not copy it as part of kerl install.

[jadeallenx]

We must have ex_doc to build the docs, so it makes sense to me that kerl would do that on user's behalf. I am very wary of making kerl also responsible for installing/maintaining rebar3 - for example, which one do we pick? What if user needs to pin some specific version of rebar3 because of local build dependencies (a plugin, for example, that doesn't work with newer or older versions of rebar3.)

So I am +1 on handling ex_doc - somewhat -1 on handling rebar3. There is too much complexity around trying to manage it imo.

[paulo-ferraz-oliveira]

Understood, and agreed.

1. we will keep having Erlang docs built and installed by kerl (for which we use ex_doc, as per ./otp_build download_ex_doc)
2. we will not do any rebar3 -related stuff for now

Edit: CI will take care of making sure the post-27 docs build on Ubuntu and macOS, at least.

[paulo-ferraz-oliveira]

@garazdawi, I opened erlang/otp#8188 since I was surprised (while testing) that a few doc targets were removed. I'm adjusting kerl considering man and pdf are no longer present, from 27 on.