Skip to content

Attempt to fix Literate + LiveServer + Documenter on Windows#203

Open
Ickaser wants to merge 1 commit into
JuliaDocs:masterfrom
Ickaser:windows-dir
Open

Attempt to fix Literate + LiveServer + Documenter on Windows#203
Ickaser wants to merge 1 commit into
JuliaDocs:masterfrom
Ickaser:windows-dir

Conversation

@Ickaser

@Ickaser Ickaser commented May 13, 2026

Copy link
Copy Markdown

I ran into #181 , and this PR basically implements the one-line suggested fix there. As far as I can tell, it seems to fix things on the LiveServer end.

HOWEVER: the slick functionality of servedocs is still not operational on my Windows machine. I'm documenting the errors here, although I'm pretty sure it has more to do with either Documenter or upstream Julia or general Windows struggles.

Following the example at https://juliadocs.org/LiveServer.jl/stable/man/ls+lit/, I set up an example directory. (In the make.jl, I add remotes=nothing to the makedocs call--can add that to PR somewhere if useful.) Then, in the REPL, I execute

servedocs(literate_dir=joinpath("docs", "literate"), skip_dir=joinpath("docs", "src", "man"))

When I open localhost:8000 everything looks alright. Then, I make a minor modification to index.md (like, adding some plain text), and LiveServer triggers a rebuild, emitting the following (plus some other noise about not having a Git repo):

[ Info: generating markdown page from `C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\literate\man\pg1.jl`
[ Info: writing result to `C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\src\man\pg1.md`
[ Info: SetupBuildDirectory: setting up build directory.

At this point, it hangs indefinitely. If I make another edit to index.md, it repeats this little loop. Ctrl+C kills LiveServer as expected, then if I run servedocs(...) again, I get

[ Info: generating markdown page from `C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\literate\man\pg1.jl`
[ Info: writing result to `C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\src\man\pg1.md`
[ Info: SetupBuildDirectory: setting up build directory.
ERROR: LoadError: IOError: rm("build\\man"): directory not empty (ENOTEMPTY)
Stacktrace:
  [1] _uv_error(prefix::String, c::Int32)
    @ Base .\libuv.jl:114
  [2] uv_error
    @ .\libuv.jl:113 [inlined]
  [3] rm(path::String; force::Bool, recursive::Bool, allow_delayed_delete::Bool)
    @ Base.Filesystem .\file.jl:317
  [4] rm(path::String; force::Bool, recursive::Bool, allow_delayed_delete::Bool)
    @ Base.Filesystem .\file.jl:303
  [5] rm
    @ .\file.jl:281 [inlined]
  [6] runner(::Type{Documenter.Builder.SetupBuildDirectory}, doc::Documenter.Document)
    @ Documenter C:\Users\ickas\.julia\packages\Documenter\AXNMp\src\builder_pipeline.jl:87
  [7] dispatch(::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Document)
    @ Documenter.Selectors C:\Users\ickas\.julia\packages\Documenter\AXNMp\src\utilities\Selectors.jl:170
  [8] #95
    @ C:\Users\ickas\.julia\packages\Documenter\AXNMp\src\makedocs.jl:283 [inlined]
  [9] withenv(::Documenter.var"#95#96"{Documenter.Document}, ::Pair{String, Nothing}, ::Vararg{Pair{String, Nothing}})
    @ Base .\env.jl:265
 [10] #93
    @ C:\Users\ickas\.julia\packages\Documenter\AXNMp\src\makedocs.jl:282 [inlined]
 [11] cd(f::Documenter.var"#93#94"{Documenter.Document}, dir::String)
    @ Base.Filesystem .\file.jl:101
 [12] makedocs(; debug::Bool, format::Documenter.HTMLWriter.HTML, kwargs::@Kwargs{…})
    @ Documenter C:\Users\ickas\.julia\packages\Documenter\AXNMp\src\makedocs.jl:281
 [13] top-level scope
    @ C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\make.jl:12
 [14] include(mapexpr::Function, mod::Module, _path::String)
    @ Base .\Base.jl:307
 [15] IncludeInto
    @ .\Base.jl:308 [inlined]
 [16] servedocs(; verbose::Bool, debug::Bool, doc_env::Bool, literate::Nothing, literate_dir::String, skip_dir::String, skip_dirs::Vector{…}, skip_files::Vector{…}, include_dirs::Vector{…}, include_files::Vector{…}, foldername::String, buildfoldername::String, makejl::String, host::String, port::Int64, launch_browser::Bool)
    @ LiveServer C:\Users\ickas\.julia\dev\LiveServer\src\utils.jl:280
 [17] top-level scope
    @ REPL[4]:1
 [18] top-level scope
    @ REPL:1
in expression starting at C:\Users\ickas\OneDrive - purdue.edu\Documents\01_Projects\temp\extra\docs\make.jl:12

which suggests to me that for some reason Documenter is getting hung up. At this point, if I delete the build directory myself from a file explorer, I can run servedocs again and things start over.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant