diff --git a/Project.toml b/Project.toml index b6fada7..0b1315f 100644 --- a/Project.toml +++ b/Project.toml @@ -4,7 +4,7 @@ authors = [ "Jonas Asprion " ] -version = "1.0.3" +version = "1.1.0" [deps] HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3" diff --git a/src/utils.jl b/src/utils.jl index f0cd6eb..4738d3f 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -23,6 +23,7 @@ function servedocs_callback!( literate::Union{Nothing,String}, skip_dirs::Vector{String}, skip_files::Vector{String}, + include_dirs::Vector{String}, foldername::String, buildfoldername::String) # ignore things happening in the build folder (generated files etc) @@ -40,7 +41,7 @@ function servedocs_callback!( if fp == path2makejl # it's easier to start from scratch (takes negligible time) empty!(dw.watchedfiles) - scan_docs!(dw, foldername, path2makejl, literate) + scan_docs!(dw, foldername, path2makejl, literate, include_dirs) end # Run a Documenter pass @@ -62,7 +63,8 @@ See the docs of the parent function `servedocs`. function scan_docs!(dw::SimpleWatcher, foldername::String, path2makejl::String, - literate::Union{Nothing,String} + literate::Union{Nothing,String}, + include_dirs::Vector{String}, )::Nothing # Typical expected structure: # docs @@ -75,9 +77,11 @@ function scan_docs!(dw::SimpleWatcher, if !isdir(foldername) || !isdir(src) error("I didn't find a $foldername/ or $foldername/src/ folder.") end - # watch the make.jl file as well as + # watch the make.jl file as well as push!(dw.watchedfiles, WatchedFile(path2makejl)) + + # include all files in the docs/src directory if isdir(foldername) # add all files in `docs/src` to watched files for (root, _, files) ∈ walkdir(joinpath(foldername, "src")), file ∈ files @@ -85,6 +89,13 @@ function scan_docs!(dw::SimpleWatcher, end end + # include all files in user-specified include directories + for idir in filter(isdir, include_dirs) + for (root, _, files) in walkdir(idir), file in files + push!(dw.watchedfiles, WatchedFile(joinpath(root, file))) + end + end + # if the user is not using Literate, return early literate === nothing && return @@ -172,6 +183,8 @@ subfolder `docs`. * `skip_dirs=[]`: same as `skip_dir` but for a list of such dirs. Takes precedence over `skip_dir`. * `skip_files=[]`: a vector of files that should not trigger regeneration. +* `include_dirs=[]`: extra source directories to watch + (in addition to `joinpath(foldername, "src")`). * `foldername="docs"`: specify a different path for the content. * `buildfoldername="build"`: specify a different path for the build. * `makejl="make.jl"`: path of the script generating the documentation relative @@ -189,6 +202,7 @@ function servedocs(; skip_dir::String="", skip_dirs::Vector{String}=String[], skip_files::Vector{String}=String[], + include_dirs::Vector{String}=String[], foldername::String="docs", buildfoldername::String="build", makejl::String="make.jl", @@ -202,6 +216,7 @@ function servedocs(; end skip_dirs = abspath.(skip_dirs) skip_files = abspath.(skip_files) + include_dirs = abspath.(include_dirs) path2makejl = joinpath(foldername, makejl) @@ -212,12 +227,12 @@ function servedocs(; docwatcher, fp -> servedocs_callback!( docwatcher, fp, path2makejl, - literate, skip_dirs, skip_files, foldername, buildfoldername + literate, skip_dirs, skip_files, include_dirs, foldername, buildfoldername ) ) # Scan the folder and update the list of files to watch - scan_docs!(docwatcher, foldername, path2makejl, literate) + scan_docs!(docwatcher, foldername, path2makejl, literate, include_dirs) # activate the doc environment if required doc_env && Pkg.activate(joinpath(foldername, "Project.toml")) diff --git a/test/utils.jl b/test/utils.jl index d998be4..cf8a183 100644 --- a/test/utils.jl +++ b/test/utils.jl @@ -23,7 +23,7 @@ include(abspath(makejl)) @test readmake() == 1 - def = (nothing, String[], String[], "docs", "build") + def = (nothing, String[], String[], String[], "docs", "build") # callback function dw = LS.SimpleWatcher() @@ -60,7 +60,7 @@ end # error if there's no docs/ folder cray = Crayon(foreground=:cyan, bold=true) println(cray, "\n⚠ Deliberately causing an error to be displayed and handled...\n") - @test_throws ErrorException LS.scan_docs!(dw, "docs", "", "") + @test_throws ErrorException LS.scan_docs!(dw, "docs", "", "", String[]) empty!(dw.watchedfiles) @@ -70,15 +70,19 @@ end write(joinpath("docs", "src", "index2.md"), "Random file") write(joinpath("docs", "make.jl"), "1+1") + mkdir("extrasrc") + write(joinpath("extrasrc", "extra.md"), "Extra source file") + mkdir(joinpath("docs", "lit")) write(joinpath("docs", "lit", "index.jl"), "1+1") - LS.scan_docs!(dw, "docs", "docs/make.jl", joinpath("docs", "lit")) + LS.scan_docs!(dw, "docs", "docs/make.jl", joinpath("docs", "lit"), [abspath("extrasrc")]) - @test length(dw.watchedfiles) == 3 # index.jl, index2.md, make.jl + @test length(dw.watchedfiles) == 4 # index.jl, index2.md, make.jl, extra.md @test endswith(dw.watchedfiles[1].path, "make.jl") @test endswith(dw.watchedfiles[2].path, "index2.md") - @test endswith(dw.watchedfiles[3].path, "index.jl") + @test endswith(dw.watchedfiles[3].path, "extra.md") + @test endswith(dw.watchedfiles[4].path, "index.jl") cd(bk) end @@ -107,7 +111,7 @@ end # callback function dw = LS.SimpleWatcher() - LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], "site", "build") + LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], String[], "site", "build") @test length(dw.watchedfiles) == 3 @test dw.watchedfiles[1].path == joinpath("site", "make.jl") @@ -118,14 +122,14 @@ end # let's now remove `index2.md` rm(joinpath("site", "src", "index2.md")) - LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], "site", "build") + LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], String[], "site", "build") # the file has been removed @test length(dw.watchedfiles) == 2 @test readmake() == 3 # let's check there's an appropriate trigger for index - LS.servedocs_callback!(dw, joinpath("site", "src", "index.md"), makejl, "", String[], String[], "site", "build") + LS.servedocs_callback!(dw, joinpath("site", "src", "index.md"), makejl, "", String[], String[], String[], "site", "build") @test length(dw.watchedfiles) == 2 @test readmake() == 4 @@ -140,7 +144,7 @@ end # error if there's no docs/ folder cray = Crayon(foreground=:cyan, bold=true) println(cray, "\n⚠ Deliberately causing an error to be displayed and handled...\n") - @test_throws ErrorException LS.scan_docs!(dw, "site", "site", "") + @test_throws ErrorException LS.scan_docs!(dw, "site", "site", "", String[]) empty!(dw.watchedfiles) @@ -153,7 +157,7 @@ end mkdir(joinpath("site", "lit")) write(joinpath("site", "lit", "index.jl"), "1+1") - LS.scan_docs!(dw, "site", "site/make.jl", joinpath("site", "lit")) + LS.scan_docs!(dw, "site", "site/make.jl", joinpath("site", "lit"), String[]) @test length(dw.watchedfiles) == 3 # index.jl, index2.md, make.jl @test endswith(dw.watchedfiles[1].path, "make.jl")