Literate scripts within Documenter cause LiveServer loop

General Usage
,
1

I’m trying to use Literate.markdown to generate pages for Documenter. The repo is here. I’m using the make.jl code below.

using Documenter
using Literate

for file ∈ ["Chapter 1: Dynamics.jl"]
    Literate.markdown(
        joinpath(@__DIR__, "..", "src", file),
        joinpath(@__DIR__, "src", "generated")
    )
end

makedocs(
    sitename = "Control Theory Notes",
    format = Documenter.HTML(),
    authors = "Joe Carpinelli",
    pages = [
        "Introduction" => "index.md",
        "Chapter 1: Dynamics" => joinpath("generated", "Chapter 1: Dynamics.md")
    ]
)

deploydocs(
    repo      = "https://github.com/cadojo/ControlTheoryNotes.jl",
    devbranch = "main"
)

When I then call LiveServer.servedocs(), the build tries and fails continuously in a loop, and I see the following error: Warning: couldn't find file "/Users/joey/GitHub/FOSS/ControlTheoryNotes.jl/docs/src/generated/<unknown>/src/Chapter 1: Dynamics.jl" when generating URL. I notice that Literate generates the following at the top of the autogenerated markdown file.

EditURL = "<unknown>/src/Chapter 1: Dynamics.jl"

Could this be the cause of the issue? I’m having trouble debugging this.

Edit: This happens even when specifying the literate keyword argument to LiveServer.servedocs.

# in ControlTheoryNotes.jl
LiveServer.servedocs(; literate = joinpath(@__DIR__, "..", "docs", "src", "generated"))
2 Likes
2

I just stumbled on the same issue. The documented solution is to set skip_dir="<generated by literate>". However, I found that it does not work for the use case as it is not respected when the file watcher of LiveServer.jl is set up. The solution to avoid the infinite loop I found is to clean up all generated files before starting “servedocs” since those would not be registered in the file watcher if they happen to be within the “docs/src” directory.