Add include_files option to servedocs (#163)

* Add `include_files` option to `servedocs`

This patch adds a new argument, `include_files::Vector{String}`, which
allows users to explicitly track individual files. In particular, this
option can be used to track individual files that would otherwise be
excluded due to being inside a `skipped_dirs` directory.

* Set version to 1.2.0.

Author: fredrikekre

Project.toml

@@ -4,7 +4,7 @@ authors = [
   "Jonas Asprion <jonas.asprion@gmx.ch",
   "Thibaut Lienart <tlienart@me.com>"
   ]
-version = "1.1.3"
+version = "1.2.0"
 
 [deps]
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"

src/utils.jl

@@ -24,24 +24,28 @@ function servedocs_callback!(
             skip_dirs::Vector{String},
             skip_files::Vector{String},
             include_dirs::Vector{String},
+            include_files::Vector{String},
             foldername::String,
             buildfoldername::String)
     # ignore things happening in the build folder (generated files etc)
     startswith(fp, joinpath(foldername, buildfoldername)) && return nothing
-    # ignore files skip_dirs and skip_files
-    for dir in skip_dirs
-         startswith(fp, dir) && return nothing
-     end
-     for file in skip_files
-         fp == file && return nothing
-     end
+
+    # ignore files in skip_dirs and skip_files (unless the file is in include_files)
+    if !(fp in include_files)
+        for dir in skip_dirs
+            startswith(fp, dir) && return nothing
+        end
+        for file in skip_files
+            fp == file && return nothing
+        end
+    end
 
     # if the file that was changed is the `make.jl` file, assume that maybe
     # new files have been generated and so refresh the vector of watched files
     if fp == path2makejl
         # it's easier to start from scratch (takes negligible time)
         empty!(dw.watchedfiles)
-        scan_docs!(dw, foldername, path2makejl, literate, include_dirs)
+        scan_docs!(dw, foldername, path2makejl, literate, include_dirs, include_files)
     end
 
     # Run a Documenter pass
@@ -65,6 +69,7 @@ function scan_docs!(dw::SimpleWatcher,
                     path2makejl::String,
                     literate::Union{Nothing,String},
                     include_dirs::Vector{String},
+                    include_files::Vector{String},
                     )::Nothing
     # Typical expected structure:
     #   docs
@@ -96,6 +101,11 @@ function scan_docs!(dw::SimpleWatcher,
         end
     end
 
+    # include all user-specified files
+    for f in filter(isfile, include_files)
+        push!(dw.watchedfiles, WatchedFile(f))
+    end
+
     # if the user is not using Literate, return early
     literate === nothing && return
 
@@ -185,6 +195,9 @@ subfolder `docs`.
 * `skip_files=[]`: a vector of files that should not trigger regeneration.
 * `include_dirs=[]`: extra source directories to watch
                      (in addition to `joinpath(foldername, "src")`).
+* `include_files=[]`: extra source files to watch. Takes precedence over
+                      `skip_dirs` so can e.g. be used to track individual
+                      files in an otherwise skipped directory.
 * `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
@@ -203,6 +216,7 @@ function servedocs(;
             skip_dirs::Vector{String}=String[],
             skip_files::Vector{String}=String[],
             include_dirs::Vector{String}=String[],
+            include_files::Vector{String}=String[],
             foldername::String="docs",
             buildfoldername::String="build",
             makejl::String="make.jl",
@@ -217,6 +231,7 @@ function servedocs(;
     skip_dirs = abspath.(skip_dirs)
     skip_files = abspath.(skip_files)
     include_dirs = abspath.(include_dirs)
+    include_files = abspath.(include_files)
 
     path2makejl = joinpath(foldername, makejl)
 
@@ -227,12 +242,12 @@ function servedocs(;
         docwatcher,
         fp -> servedocs_callback!(
                 docwatcher, fp, path2makejl,
-                literate, skip_dirs, skip_files, include_dirs, foldername, buildfoldername
+                literate, skip_dirs, skip_files, include_dirs, include_files, foldername, buildfoldername
         )
     )
 
     # Scan the folder and update the list of files to watch
-    scan_docs!(docwatcher, foldername, path2makejl, literate, include_dirs)
+    scan_docs!(docwatcher, foldername, path2makejl, literate, include_dirs, include_files)
 
     # 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[], String[], "docs", "build")
+    def = (nothing, String[], 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", "", "", String[])
+    @test_throws ErrorException LS.scan_docs!(dw, "docs", "", "", String[], String[])
 
     empty!(dw.watchedfiles)
 
@@ -70,19 +70,23 @@ 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("extradir")
+    write(joinpath("extradir", "extra.md"), "Extra source file")
+
+    mkdir("extradir2")
+    write(joinpath("extradir2", "extra2.md"), "Extra source file 2")
 
     mkdir(joinpath("docs", "lit"))
     write(joinpath("docs", "lit", "index.jl"), "1+1")
 
-    LS.scan_docs!(dw, "docs", "docs/make.jl", joinpath("docs", "lit"), [abspath("extrasrc")])
+    LS.scan_docs!(dw, "docs", "docs/make.jl", joinpath("docs", "lit"), [abspath("extradir")], [abspath("extradir2", "extra2.md")])
 
-    @test length(dw.watchedfiles) == 4 # index.jl, index2.md, make.jl, extra.md
+    @test length(dw.watchedfiles) == 5 # index.jl, index2.md, make.jl, extra.md, extra2.md
     @test endswith(dw.watchedfiles[1].path, "make.jl")
     @test endswith(dw.watchedfiles[2].path, "index2.md")
     @test endswith(dw.watchedfiles[3].path, "extra.md")
-    @test endswith(dw.watchedfiles[4].path, "index.jl")
+    @test endswith(dw.watchedfiles[4].path, "extra2.md")
+    @test endswith(dw.watchedfiles[5].path, "index.jl")
 
     cd(bk)
 end
@@ -111,7 +115,7 @@ end
     # callback function
     dw = LS.SimpleWatcher()
 
-    LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], String[], "site", "build")
+    LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], String[], String[], "site", "build")
 
     @test length(dw.watchedfiles) == 3
     @test dw.watchedfiles[1].path == joinpath("site", "make.jl")
@@ -122,14 +126,14 @@ end
 
     # let's now remove `index2.md`
     rm(joinpath("site", "src", "index2.md"))
-    LS.servedocs_callback!(dw, makejl, makejl, "", String[], String[], String[], "site", "build")
+    LS.servedocs_callback!(dw, makejl, makejl, "", String[], 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[], String[], "site", "build")
+    LS.servedocs_callback!(dw, joinpath("site", "src", "index.md"), makejl, "", String[], String[], String[], String[], "site", "build")
     @test length(dw.watchedfiles) == 2
     @test readmake() == 4
 
@@ -144,7 +148,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", "", String[])
+    @test_throws ErrorException LS.scan_docs!(dw, "site", "site", "", String[], String[])
 
     empty!(dw.watchedfiles)
 
@@ -157,7 +161,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"), String[])
+    LS.scan_docs!(dw, "site", "site/make.jl", joinpath("site", "lit"), String[], String[])
 
     @test length(dw.watchedfiles) == 3 # index.jl, index2.md, make.jl
     @test endswith(dw.watchedfiles[1].path, "make.jl")