Add index.html generation for redirecting to ./stable or ./dev

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Documenter.jl changelog
 
+## Version `v0.27.6`
+* ![Feature][badge-feature] Add support for generating `index.html` to redirect to `dev` or `stable`. The redirected destination is the same as the outdated warning. If there's already user-generated `index.html`, Documenter will not overwrite the file. ([#937][github-937], [#1657][github-1657], [#1658][github-1658])
+
 ## Version `v0.27.5`
 
 * ![Bugfix][badge-bugfix] Fix an error introduced in version `v0.27.4` (PR[#1634][github-1634]) which was triggered by trailing comments in `@eval`/`@repl`/`@example` blocks. ([#1655](github-1655), [#1661](github-1661))
@@ -686,6 +689,7 @@
 [github-929]: https://github.com/JuliaDocs/Documenter.jl/pull/929
 [github-934]: https://github.com/JuliaDocs/Documenter.jl/pull/934
 [github-935]: https://github.com/JuliaDocs/Documenter.jl/pull/935
+[github-937]: https://github.com/JuliaDocs/Documenter.jl/issues/937
 [github-938]: https://github.com/JuliaDocs/Documenter.jl/pull/938
 [github-941]: https://github.com/JuliaDocs/Documenter.jl/pull/941
 [github-946]: https://github.com/JuliaDocs/Documenter.jl/pull/946
@@ -893,6 +897,8 @@
 [github-1647]: https://github.com/JuliaDocs/Documenter.jl/pull/1647
 [github-1649]: https://github.com/JuliaDocs/Documenter.jl/pull/1649
 [github-1655]: https://github.com/JuliaDocs/Documenter.jl/issues/1655
+[github-1657]: https://github.com/JuliaDocs/Documenter.jl/pull/1657
+[github-1658]: https://github.com/JuliaDocs/Documenter.jl/pull/1658
 [github-1661]: https://github.com/JuliaDocs/Documenter.jl/pull/1661
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079

src/Documenter.jl

@@ -607,6 +607,10 @@ function git_push(
             # This must always happen after the folder copying.
             Writers.HTMLWriter.generate_version_file(joinpath(dirname, "versions.js"), entries, symlinks)
 
+            # Create the index.html file to redirect ./stable or ./dev.
+            # This must always happen after the folder copying.
+            Writers.HTMLWriter.generate_redirect_file(joinpath(dirname, "index.html"), entries)
+
             # generate the symlinks, make sure we don't overwrite devurl
             cd(dirname) do
                 for kv in symlinks

src/Writers/HTMLWriter.jl

@@ -1405,6 +1405,20 @@ function generate_version_file(versionfile::AbstractString, entries, symlinks =
     end
 end
 
+# write redirect file
+function generate_redirect_file(redirectfile::AbstractString, entries)
+    # The link to the redirected destination is same as outdated-warning. (DOCUMENTER_STABLE)
+
+    comment = "<!--This file is automatically generated by Documenter.jl-->"
+
+    isfile(redirectfile) && !startswith(read(redirectfile, String), comment) && return
+
+    open(redirectfile, "w") do buf
+        println(buf, comment)
+        println(buf, "<meta http-equiv=\"refresh\" content=\"0; url=./$(first(entries))/\"/>")
+    end
+end
+
 function generate_siteinfo_file(dir::AbstractString, version::AbstractString)
     open(joinpath(dir, "siteinfo.js"), "w") do buf
         println(buf, "var DOCUMENTER_CURRENT_VERSION = \"$(version)\";")

test/htmlwriter.jl

@@ -3,7 +3,7 @@ module HTMLWriterTests
 using Test
 using Documenter
 using Documenter: DocSystem
-using Documenter.Writers.HTMLWriter: HTMLWriter, generate_version_file, expand_versions
+using Documenter.Writers.HTMLWriter: HTMLWriter, generate_version_file, generate_redirect_file, expand_versions
 
 function verify_version_file(versionfile, entries)
     @test isfile(versionfile)
@@ -16,6 +16,13 @@ function verify_version_file(versionfile, entries)
     end
 end
 
+function verify_redirect_file(redirectfile, version)
+    @test isfile(redirectfile)
+    content = read(redirectfile, String)
+
+    @test occursin("url=./$(version)/", content)
+end
+
 @testset "HTMLWriter" begin
     @test isdir(HTMLWriter.ASSETS)
     @test isdir(HTMLWriter.ASSETS_SASS)
@@ -104,17 +111,21 @@ end
 
     mktempdir() do tmpdir
         versionfile = joinpath(tmpdir, "versions.js")
+        redirectfile = joinpath(tmpdir, "index.html")
+        devurl = "dev"
         versions = ["stable", "dev",
                     "2.1.1", "v2.1.0", "v2.0.1", "v2.0.0",
                     "1.1.1", "v1.1.0", "v1.0.1", "v1.0.0",
                     "0.1.1", "v0.1.0"] # note no `v` on first ones
+
+        # make dummy directories of versioned docs
         cd(tmpdir) do
             for version in versions
                 mkdir(version)
             end
         end
 
-        # expanding versions
+        # case1: default versioning
         versions = ["stable" => "v^", "v#.#", "dev" => "dev"] # default to makedocs
         entries, symlinks = expand_versions(tmpdir, versions)
         @test entries == ["stable", "v2.1", "v2.0", "v1.1", "v1.0", "v0.1", "dev"]
@@ -124,7 +135,10 @@ end
                            "v1.1.1"=>"1.1.1", "v0.1.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "stable")
 
+        # case2: major released versions
         versions = ["v#"]
         entries, symlinks = expand_versions(tmpdir, versions)
         @test entries == ["v2.1", "v1.1"]
@@ -133,7 +147,10 @@ end
                            "v2.1.1"=>"2.1.1", "v1.1.1"=>"1.1.1", "v0.1.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1")
 
+        # case3: all released versions
         versions = ["v#.#.#"]
         entries, symlinks = expand_versions(tmpdir, versions)
         @test entries == ["v2.1.1", "v2.1.0", "v2.0.1", "v2.0.0", "v1.1.1", "v1.1.0",
@@ -143,7 +160,10 @@ end
                            "v2.0"=>"v2.0.1", "v1.1"=>"1.1.1", "v1.0"=>"v1.0.1", "v0.1"=>"0.1.1"]
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1.1")
 
+        # case4: invalid versioning
         versions = ["v^", "devel" => "dev", "foobar", "foo" => "bar"]
         entries, symlinks = @test_logs(
             (:warn, "no match for `versions` entry `\"foobar\"`"),
@@ -155,9 +175,29 @@ end
         @test ("devel" => "dev") in symlinks
         generate_version_file(versionfile, entries)
         verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "v2.1")
 
+        # case5: invalid versioning
         versions = ["stable" => "v^", "dev" => "stable"]
         @test_throws ArgumentError expand_versions(tmpdir, versions)
+
+        # case6: default versioning (no released version)
+        cd(tmpdir) do
+            # remove dummy directories
+            for dir in readdir(tmpdir)
+                rm(dir)
+            end
+            mkdir("dev")
+        end
+        versions = ["stable" => "v^", "v#.#", "dev" => "dev"] # default to makedocs
+        entries, symlinks = expand_versions(tmpdir, versions)
+        @test entries == ["dev"]
+        @test symlinks == []
+        generate_version_file(versionfile, entries)
+        verify_version_file(versionfile, entries)
+        generate_redirect_file(redirectfile, entries)
+        verify_redirect_file(redirectfile, "dev")
     end
 
     # Exhaustive Conversion from Markdown to Nodes.