IOError on ispath(".../.documenter/.documenter/.documenter/...") when rebuilding documentation locally with build_vitepress=false and npm run docs:dev running

[henrik-wolf]

I am trying to develop a local version of my documentation according to the readme:

Starting from a clean setup using DocumenterVitepress.generate_template(...), I modified the makedocs function to read:

makedocs(;
    modules=[HelloWorld],
    authors="Your Name Here",
    remotes=nothing,
    sitename="HelloWorld.jl",
    format=DocumenterVitepress.MarkdownVitepress(
        repo="https://github.com/YourGithubUsername/HelloWorld.jl",
        devurl="dev",
        deploy_url="yourgithubusername.github.io/HelloWorld.jl",
        build_vitepress=false
    ),
    pages=[
        "Home" => "index.md",
    ],
    warnonly=true,
)

I then run julia --project=. make.jl in the docs folder, followed by npm run docs:dev, which successfully starts a server on which I can see the documentation.
With the running server, I then try to rebuild the docs, again using julia --project=. make.jl. This causes the build process to crash with:
(note the length of the first line)

ERROR: LoadError: IOError: ispath("/Users/henrikwolf/HelloWorld/docs/build/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter/.documenter"): name too long (ENAMETOOLONG)
Stacktrace:
  [1] uv_error
    @ ./libuv.jl:106 [inlined]
  [2] ispath(path::String)
    @ Base.Filesystem ./stat.jl:334
  [3] checkfor_mv_cp_cptree(src::String, dst::String, txt::String; force::Bool)
    @ Base.Filesystem ./file.jl:320
  [4] checkfor_mv_cp_cptree
    @ ./file.jl:318 [inlined]
  [5] cptree(src::String, dst::String; force::Bool, follow_symlinks::Bool)
    @ Base.Filesystem ./file.jl:343
  [6] cptree(src::String, dst::String; force::Bool, follow_symlinks::Bool) (repeats 78 times)
    @ Base.Filesystem ./file.jl:350
  [7] cptree
    @ ./file.jl:340 [inlined]
  [8] cp(src::String, dst::String; force::Bool, follow_symlinks::Bool)
    @ Base.Filesystem ./file.jl:384
  [9] cp
    @ ./file.jl:378 [inlined]
 [10] render(doc::Documenter.Document, settings::MarkdownVitepress)
    @ DocumenterVitepress ~/.julia/packages/DocumenterVitepress/8qgu7/src/writer.jl:138
 [11] runner(::Type{DocumenterVitepress.MarkdownFormat}, fmt::MarkdownVitepress, doc::Documenter.Document)
    @ DocumenterVitepress ~/.julia/packages/DocumenterVitepress/8qgu7/src/DocumenterVitepress.jl:28
 [12] dispatch(::Type{Documenter.FormatSelector}, ::MarkdownVitepress, ::Vararg{Any})
    @ Documenter.Selectors ~/.julia/packages/Documenter/Bs999/src/utilities/Selectors.jl:170
 [13] render(doc::Documenter.Document)
    @ Documenter ~/.julia/packages/Documenter/Bs999/src/writers.jl:45
 [14] runner(::Type{Documenter.Builder.RenderDocument}, doc::Documenter.Document)
    @ Documenter ~/.julia/packages/Documenter/Bs999/src/builder_pipeline.jl:266
 [15] dispatch(::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Document)
    @ Documenter.Selectors ~/.julia/packages/Documenter/Bs999/src/utilities/Selectors.jl:170
 [16] #89
    @ ~/.julia/packages/Documenter/Bs999/src/makedocs.jl:273 [inlined]
 [17] withenv(::Documenter.var"#89#91"{Documenter.Document}, ::Pair{String, Nothing}, ::Vararg{Pair{String, Nothing}})
    @ Base ./env.jl:265
 [18] #88
    @ ~/.julia/packages/Documenter/Bs999/src/makedocs.jl:272 [inlined]
 [19] cd(f::Documenter.var"#88#90"{Documenter.Document}, dir::String)
    @ Base.Filesystem ./file.jl:112
 [20] makedocs(; debug::Bool, format::MarkdownVitepress, kwargs::@Kwargs{modules::Vector{Module}, authors::String, remotes::Nothing, sitename::String, pages::Vector{Pair{String, String}}, warnonly::Bool})
    @ Documenter ~/.julia/packages/Documenter/Bs999/src/makedocs.jl:271
 [21] top-level scope
    @ ~/HelloWorld/docs/make.jl:5
in expression starting at /Users/henrikwolf/HelloWorld/docs/make.jl:5

rebuilding without the running server works fine.

versioninfo() gives:

Julia Version 1.11.2
Commit 5e9a32e7af2 (2024-12-01 20:02 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: macOS (arm64-apple-darwin24.0.0)
  CPU: 8 × Apple M1
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, apple-m1)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)

[thofma]

(Not a solution, just a confirmation that I have seen this too and incorporated a rm -rf docs/build when rebuilding the documentation.)

[lazarusA]

is an issue with the hot watcher from vitepress. I would say that the most clean way to resolve the issue is by stopping the server before generating new files.

try run(`pkill -f vitepress`) catch end
# now do

makedocs(;
)

I added some tips in #198

[thofma]

Very unfortunate that this does not work. Lettting the vitepress run while rebuilding the documentation was exactly what we were doing to speed up development.

[lazarusA]

yes, not sure exactly where is the limit. I usually rebuild the files locally without any issues for most of my packages while keeping the vitepress server running. Hence, maybe further investigation is needed to pin down exactly when this happens.