DocumentationGenerator.jl failing with custom docs/make.jl

[tkf]

The documentation of Transducers.jl in JuliaHub is broken https://juliahub.com/docs/Transducers/cATK6/0.4.35/. When it's built correctly, it'd be something like https://juliafolds.github.io/Transducers.jl/dev.

I think this is because DocumentationGenerator.jl tries to rewrite docs/make.jl

DocumentationGenerator.jl/src/utils/rewrite.jl

Lines 18 to 23 in f3a8759

	fix_makefile(makefile)
	Takes in the path to a Documenter.jl-compatible `make.jl` file and
	1. Removes all calls to `deploydocs`.
	2. Records the custom `build` kwarg in the `makedocs` call.
	3. Makes sure that `format` is set to `Documenter.HTML(...)` in the `makedocs` call.

while Transducers.jl has a bit unusual docs/make.jl

https://github.com/JuliaFolds/Transducers.jl/blob/dcd07701570a5e3d14085fa95ff509daccb05048/docs/make.jl#L14-L22

It'd be nice if we can take a bit more declarative approach. For example, how about asking user to (optionally) create docs/build.jl which must define a function (say) build. Something like

using Documenter

build(; kwargs...) = makedocs(;
    # User's setup
    modules = [Transducers],
    pages = [...],
    ...,
    # Let DocumentationGenerator.jl override some keyword arguments:
    kwargs...,
)

Then, docs/make.jl would be

include("build.jl")
build()
deploydocs(...)