Add generate_redirects function to generate HTML redirects of Documenter sites

CHANGELOG.md

@@ -1,5 +1,9 @@
 # DocumenterTools.jl changelog
 
+## Unreleased
+
+* ![Enhancement][badge-enhancement] DocumenterTools now provides a `DocumenterTools.walkdocs` function. ([#75][github-75])
+
 ## Version `v0.1.17`
 
 * ![Enhancement][badge-enhancement] The compiled CSS files generated by DocumenterTools are now minified. ([#71][github-71])
@@ -102,6 +106,7 @@ Maintenance release declaring compatibility with Documenter 0.25. ([#39][github-
 [github-64]: https://github.com/JuliaDocs/DocumenterTools.jl/issues/64
 [github-65]: https://github.com/JuliaDocs/DocumenterTools.jl/pull/65
 [github-71]: https://github.com/JuliaDocs/DocumenterTools.jl/pull/71
+[github-75]: https://github.com/JuliaDocs/DocumenterTools.jl/pull/75
 
 
 [badge-breaking]: https://img.shields.io/badge/BREAKING-red.svg

src/DocumenterTools.jl

@@ -174,6 +174,8 @@ function package_devpath(pkg::Module)
     return normpath(joinpath(path, "..", ".."))
 end
 
+include("walkdocs.jl")
+include("redirects.jl")
 include("genkeys.jl")
 include("Generator.jl")
 include("Themes.jl")

src/OutdatedWarning.jl

@@ -1,6 +1,7 @@
 export OutdatedWarning
 
 module OutdatedWarning
+import ..DocumenterTools
 using Gumbo, AbstractTrees, Documenter
 
 OLD_VERSION_CSS = replace("""
@@ -168,20 +169,18 @@ function generate(io::IO, root::String;force = false)
         end
 
         print(io, "Processing $(dir): ")
-        for (root, _, files) in walkdir(path)
-            for file in files
-                _, ext = splitext(file)
-                if ext == ".html"
-                    try
-                        did_change = add_old_docs_notice(joinpath(root, file), force)
-                        print(io, did_change ? "✓" : ".")
-                    catch err
-                        if err isa InterruptException
-                            rethrow()
-                        end
-                        @debug "Fatally failed to add a outdated warning" exception = (err, catch_backtrace())
-                        print(io, "!")
+        DocumenterTools.walkdocs(path) do fileinfo
+            _, ext = splitext(fileinfo.filename)
+            if ext == ".html"
+                try
+                    did_change = add_old_docs_notice(fileinfo.fullpath, force)
+                    print(io, did_change ? "✓" : ".")
+                catch err
+                    if err isa InterruptException
+                        rethrow()
                     end
+                    @debug "Fatally failed to add a outdated warning" exception = (err, catch_backtrace())
+                    print(io, "!")
                 end
             end
         end

src/redirects.jl

@@ -0,0 +1,48 @@
+"""
+    generate_redirects(;
+        src::AbstractString,
+        out::AbstractString,
+        rooturl::AbstractString,
+        force::Bool=false,
+    )
+
+Given a Documenter-generated HTML documentation directory `src`, generates a corresponding
+directory where each of the HTML files is replaced by a redirect to the corresponding file
+on the under `rooturl`.
+
+Technically, the function replaces each of the HTML files with a HTML file that contains
+a `<meta http-equiv="refresh" content="0` redirect.
+
+If `force = true`, the destination `out` will first be deleted.
+"""
+function generate_redirects(;
+        src::AbstractString,
+        out::AbstractString,
+        rooturl::AbstractString,
+        force::Bool=false,
+    )
+    rooturl = rstrip(rooturl, '/')
+    outdir = abspath(out)
+    if ispath(outdir)
+        if force
+            @warn "Destination path exists, removing" force outdir
+            rm(outdir, recursive=true, force=true)
+        else
+            error("output directory already exists: $outdir")
+        end
+    end
+    mkpath(outdir)
+    # Walk over all the HTML files in the source directory and generate the
+    # corresponding HTML redirect file.
+    walkdocs(src) do fileinfo
+        path_elements = splitpath(fileinfo.relpath)
+        mkpath(joinpath(outdir, path_elements[1:end-1]...))
+        open(joinpath(outdir, path_elements...), write=true) do io
+            redirect_url = join((rooturl, path_elements...), '/')
+            write(io, """
+            <!--This file is automatically generated by Documenter.jl-->
+            <meta http-equiv="refresh" content="0; url=$(redirect_url)"/>
+            """)
+        end
+    end
+end

src/walkdocs.jl

@@ -0,0 +1,41 @@
+"""
+    walkdocs(f, dir::AbstractString; collect::Bool=false)
+
+Takes a directory `dir`, which is assumed to contain Documenter-generated HTML documentation,
+walks over all the files and calls `f` on each of the HTML files it find. `f` will be called
+with a single object that has the following fields (all strings):
+
+- `root`: the root directory of the walk, i.e. `dir` (but as an absolute path)
+- `filename`: file name
+- `relpath`: path to the file, relative to `dir`
+- `fullpath`: absolute path to the file
+
+If `collect = true` is set, the function also "collects" all the return values from `f`
+from each of the function calls, essentially making `walkdocs` behave like a `map` function
+applied on each of the HTML files.
+"""
+function walkdocs(f, dir::AbstractString; collect::Bool=false)
+    dir = abspath(dir)
+    isdir(dir) || error("docwalker: dir is not a directory\n dir = $(dir)")
+
+    mapped_collection = collect ? Any[] : nothing
+    for (root, _, files) in walkdir(dir)
+        for file in files
+            _, ext = splitext(file)
+            (ext == ".html") || continue
+            file_fullpath = joinpath(root, file)
+            file_relpath = Base.relpath(file_fullpath, dir)
+            fileinfo = (;
+                root = dir,
+                filename = file,
+                relpath = file_relpath,
+                fullpath = file_fullpath,
+            )
+            r = f(fileinfo)
+            if collect
+                push!(mapped_collection, r)
+            end
+        end
+    end
+    return mapped_collection
+end

test/outdated.jl

@@ -16,12 +16,13 @@ mktempdir() do TMP
     cp(joinpath(TMP, "fixtures", "pre"), transient_path, force=true)
     OutdatedWarning.generate(transient_path)
 
-    for (root, _, files) in walkdir(transient_path)
-        for file in files
-            content = read(joinpath(root, file), String)
-            expected = read(joinpath(replace(root, "transient" => "post"), file), String)
-            @test replace(content, "\r\n" => "\n") == replace(expected, "\r\n" => "\n")
-        end
+    DocumenterTools.walkdocs(transient_path) do fileinfo
+        content = read(fileinfo.fullpath, String)
+        expected = read(
+            joinpath(replace(dirname(fileinfo.fullpath), "transient" => "post"), fileinfo.filename),
+            String
+        )
+        @test replace(content, "\r\n" => "\n") == replace(expected, "\r\n" => "\n")
     end
 
     rm(joinpath(TMP, "fixtures"), recursive=true)

test/runtests.jl

@@ -19,6 +19,10 @@ import Documenter
         DocumenterTools.genkeys(DocumenterMarkdown)
     end
 
+    @testset "walkdocs" begin
+        include("walkdocs.jl")
+    end
+
     @testset "outdated warnings" begin
         include("outdated.jl")
     end

test/walkdocs.jl

@@ -0,0 +1,19 @@
+let fileinfos = []
+    rs = DocumenterTools.walkdocs(joinpath(@__DIR__, "fixtures")) do fileinfo
+        push!(fileinfos, fileinfo)
+
+        @test isabspath(fileinfo.root)
+        @test isabspath(fileinfo.fullpath)
+        @test !isabspath(fileinfo.relpath)
+        @test joinpath(fileinfo.root, fileinfo.relpath) == fileinfo.fullpath
+    end
+    @test rs === nothing
+    @test length(fileinfos) == 10
+end
+
+let rs = DocumenterTools.walkdocs(joinpath(@__DIR__, "fixtures"), collect=true) do fileinfo
+        fileinfo.root
+    end
+    @test length(rs) == 10
+    @test all(s -> isa(s, String), rs)
+end