28.0-rc build failure due to ex_doc warnings

[adamcstephens]

Describe the bug
Failed during building documentations due to warnings treated as errors.

To Reproduce
Build OTP. This is a Nix build for nixpkgs.

Expected behavior
No failure

Affected versions
OTP 28.0-rc2 (or rc1)

Additional context

erlang-28.0-rc>  GEN	man_index.md
erlang-28.0-rc>  GEN	../../../doc/index.html
erlang-28.0-rc> warning: jinterface.html redirects to ../lib/jinterface/doc/html/index.html, which does not exist
erlang-28.0-rc> 
erlang-28.0-rc> warning: odbc.html redirects to ../lib/odbc/doc/html/index.html, which does not exist
erlang-28.0-rc> 
erlang-28.0-rc> View "html" docs at "/build/source/doc/index.html"
erlang-28.0-rc> ex_doc emitted warnings
erlang-28.0-rc> make[3]: *** [/build/source/make/doc.mk:76: ../../../doc/index.html] Error 1
erlang-28.0-rc> make[3]: Leaving directory '/build/source/system/doc/top'
erlang-28.0-rc> make[2]: *** [/build/source/make/otp_release_targets.mk:41: release_docs] Error 2
erlang-28.0-rc> make[2]: Leaving directory '/build/source/system/doc/top'
erlang-28.0-rc> make[1]: *** [Makefile:442: release_docs] Error 2
erlang-28.0-rc> make[1]: Leaving directory '/build/source'
erlang-28.0-rc> make: *** [Makefile:861: install-docs] Error 2

[adamcstephens]

If we're missing something in our nix build definition, please let me know. We don't have these problems with 27.1 which appears to include #8596

[garazdawi]

It is an update of ex_doc that produces this new warning. You can disable warnings as error for the doc build by setting EX_DOC_WARNINGS_AS_ERRORS=false before running make docs.

I suppose that maybe a better question though is, why are you building the html docs in nix?

[adamcstephens]

Yeah, I found the warning disabling flag and used that. I figured it was worthwhile to file the bug though in case it should be fixed during the RC phase.

Why are we building the docs? I can't answer that as we were already doing so prior to my working on these packages. It's a great question though, and not building them would simplify things for us.

[adamcstephens]

Looks like the install-docs target was added for 18.3.4 and we've been copying/carrying it along since then. https://github.com/NixOS/nixpkgs/pull/16244/files#diff-f5b7dbc04ba0ca072daeaf5979283b10ca66353bf749e1854fae65d80d4afc78R74

[garazdawi]

I think what you want to do is to do make install-docs DOC_TARGETS="chunks man", as it is the shell/IDE docs you want and possibly man pages.

I think I may also make it so that if any application is not built, then I will disable warnings as errors as there are no guarantees at all that the link checks will work in such circumstances.

[garazdawi]

#9620 should fix the issue

[adamcstephens]

Thanks for the pointer to DOCS_TARGETS, I've updated our build to use that and simplified the build chain.