Infinite loop with Literate

[kescobo]

I have a package where I'm trying to generate some pages with Literate.jl, while most pages use regular markdown (link to branch), but when I run servedocs(), it keeps looping to rebuild even without changing any of the files.

This was mentioned in #86 and #68 (comment) but is supposed to be fixed as of #85 (and I'm on v0.3.6).

Here's what I have in make.jl to build the markdown with Literate:

lsrc = joinpath(@__DIR__, "lectures")
lslides = joinpath(@__DIR__, "lectures", "slides")
outdir = joinpath(@__DIR__, "src", "Lectures")

for l in readdir(lsrc, join=true)
    isfile(l) || continue
    splitext(l)[2] == ".jl" || continue
    Literate.markdown(l, outdir)
    Literate.notebook(l, lslides, execute=false)
end

This runs correctly with julia --project=docs docs/make.jl and deploys correctly with github actions. If I comment out these lines, it works fine with LiveServer. Otherwise:

julia> using BISC195, LiveServer

julia> servedocs(literate=joinpath("docs","lectures"))
[ Info: generating markdown page from `~/.julia/dev/BISC195/docs/lectures/lecture1.jl`
[ Info: writing result to `~/.julia/dev/BISC195/docs/src/lectures/lecture1.md`
[ Info: generating notebook from `~/.julia/dev/BISC195/docs/lectures/lecture1.jl`
[ Info: writing result to `~/.julia/dev/BISC195/docs/lectures/slides/lecture1.ipynb`
[ Info: SetupBuildDirectory: setting up build directory.
# output truncated....
┌ Warning: couldn't find file "/Users/ksb/.julia/dev/BISC195/docs/src/lectures/<unknown>/docs/lectures/lecture1.jl" when generating URL
└ @ Documenter.Utilities ~/.julia/packages/Documenter/PLD7m/src/Utilities/Utilities.jl:368
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/PLD7m/src/deployconfig.jl:41
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)
[ Info: generating markdown page from `~/.julia/dev/BISC195/docs/lectures/lecture1.jl
# ... continue looping

I'm sure I'm doing this wrong, but I can't figure out what it is

[tlienart]

Hello Kevin! Your link doesn't work for me but this is fairly easy to debug, basically LiveServer by default looks at stuff and, if it sees changes, triggers. Now if the trigger generates files that LiveServer is watching, it will re-trigger whence the infinite loop.

This typically happens when your make.jl file generates other files in your src/ folder.

To avoid this, you just need to see what is being generated with a pass (here a pass of make.jl) and if it generates auxiliary files, these should not be watched.

In this case you just need to (1) get the generated stuff to be generated in a folder (2) skip that folder with the skip_dir keyword. I suspect that your literate commands generate files which trigger the build.

Hope that makes sense, otherwise consider adding me to your repo and I'll have a look.

[kescobo]

Whoops - sorry. I merged and deleted that branch 🤦 . Here's the link to the merge commit (and I updated it above).

Thanks, that works! I modified the folder structure to simplify where outputs go. Took a bit of fiddling, because I read the docs for skip_dir quickly

skip_dir="" is a subpath of docs/ where modifications should not trigger the generation of the docs...

And tried skip_dir=joinpath("src", "Lectures"), when what I needed was skip_dir=joinpath("docs", "src", "Lectures"). The example in the doc string shows this clearly, but the "subpath of docs/" language is a bit misleading.

Also, the literate= kwarg doesn't seem to be necessary. Turns out I don't have any idea what that's doing... but oh well! It's functional.

[tlienart]

hahaha! well I'm glad you figured it out :)