Add include_dirs to servedocs (#154)

This patch add a new keyword argument `include_dirs` to `servedocs`
which make it possible to add additional source directories (in addition
to `docs/src`) that should be considered for the file watching. This
does, for example, make it possible to watch the source files of your
package, and call `Revise.revise()` in `docs/make.jl` in order to
automatically update docstrings.

Project.toml

@@ -4,7 +4,7 @@ authors = [
   "Jonas Asprion <[email protected]",
   "Thibaut Lienart <[email protected]>"
   ]
-version = "1.0.3"
+version = "1.1.0"
 
 [deps]
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"

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,16 +77,25 @@ 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
             push!(dw.watchedfiles, WatchedFile(joinpath(root, file)))
         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"))

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")