building the documentation for JuliaInterface

[ThomasBreuer]

@fingolfin wrote in the discussion of pull request #617:

I just realized that we never really build the documentation for JuliaInterface, do we? We probably should (HTML+TXT only, no PDF, so that user's don't need LaTeX). But how?? We have to be careful to do it only after GAP actually runs, so we can't do it during precompilation as part of regenerate_gaproot() (I think).

Next best I can think of is to delete any generated documentation files in regenerate_gaproot(), and then regenerate them in __init__ if we notice they are missing (this way, we always regenerate them if needed).

Another solution would be to be slightly nasty and commit the relevant files (*.html, *.txt, *.js, *.css, ...) into the repository...

Or if JuliaInterface was built into a JLL (see issue #619), then that JLL could contain the generated documentation, too.

[ThomasBreuer]

I thought that "compiling" the documentation of a package is needed only when a release is made, and then it is only necessary to add the result to the package archive --is this perhaps meant with the "Another solution" statement (and then this applies also to the JLL solution)?

[fingolfin]

Here's the thing: for GAP packages, normally we do indeed build the documentation when a release is made, and package it all together into a tarball.

But for Julia packages, a "release" basically is a tag on a repository, and the Julia package manager deploys a snapshot of that (indeed, if one uses Pkg.develop, it uses an actual clone of the package repository). I am not aware of any way to add additional files in there -- well, other than to do so "manually" via deps/build.jl, or as part of precompilation etc.

So when users install GAP.jl, they just get what's in the repo, nothing more. Hence this issue.

[fingolfin]

Just stumbled over this independently again. My first idea to deal with this (for now) was to edit regenerate_gaproot() which currently compiles JuliaInterface using this code:

    cd(joinpath(gaproot_gapjl, "pkg", "JuliaInterface")) do
        run(pipeline(`./configure $gaproot_mutable`, stdout="build.log"))
        run(pipeline(`make V=1 -j$(Sys.CPU_THREADS)`, stdout="build.log", append=true))
    end

... and then insert a step to build the documentation. But that requires GAP! But we don't know of any GAP installation to use on the system, except the one we have in GAP.jl... but that is not (yet) runnable at the time regenerate_gaproot runs. So this idea doesn't work.

On the other hand, a JuliaInterface JLL (see #619) could solve this, as it could of course contain a compiled version of the manual, too.