From c4086b67e165aecdfceb6e9178557ebd9c4e96ed Mon Sep 17 00:00:00 2001 From: hyrodium Date: Thu, 22 Jul 2021 23:37:59 +0900 Subject: [PATCH 01/12] add generation of index.html to redirect to ./stable or ./dev --- src/Documenter.jl | 4 ++++ src/Writers/HTMLWriter.jl | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/src/Documenter.jl b/src/Documenter.jl index b0ea708e7b..1c59e885ac 100644 --- a/src/Documenter.jl +++ b/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, devurl, versions) + # generate the symlinks, make sure we don't overwrite devurl cd(dirname) do for kv in symlinks diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index bd2ae23f1e..0e51bd8d8b 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -1405,6 +1405,25 @@ function generate_version_file(versionfile::AbstractString, entries, symlinks = end end +# write redirect file +function generate_redirect_file(redirectfile::AbstractString, entries, devurl, versions) + # If `versions` contains "stable"=>"v^" and `entries` contains "stable", then version="stable". + # In other cases, version="dev". + + version = devurl + stable_index = findfirst(v -> last(v)=="v^", versions) + if !isnothing(stable_index) + stable_version = first(versions[stable_index]) + if stable_version in entries + version = stable_version + end + end + + open(redirectfile, "w") do buf + println(buf, "") + 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)\";") From ab036cb0a065419dc451492ad814479b6a772f1e Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sat, 24 Jul 2021 21:00:33 +0900 Subject: [PATCH 02/12] update generate_redirect_file to check generated comment --- src/Writers/HTMLWriter.jl | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 0e51bd8d8b..9d79302926 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -1410,6 +1410,10 @@ function generate_redirect_file(redirectfile::AbstractString, entries, devurl, v # If `versions` contains "stable"=>"v^" and `entries` contains "stable", then version="stable". # In other cases, version="dev". + comment = "" + + isfile(redirectfile) && !startswith(read(redirectfile, String), comment) && return + version = devurl stable_index = findfirst(v -> last(v)=="v^", versions) if !isnothing(stable_index) @@ -1420,6 +1424,7 @@ function generate_redirect_file(redirectfile::AbstractString, entries, devurl, v end open(redirectfile, "w") do buf + println(buf, comment) println(buf, "") end end From 30676a697c1ac0c8319ef03f58bec6da62ead34e Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sun, 25 Jul 2021 03:26:17 +0900 Subject: [PATCH 03/12] add tests for generate_redirect_file --- test/htmlwriter.jl | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/test/htmlwriter.jl b/test/htmlwriter.jl index b95d20977f..26ea48f3f9 100644 --- a/test/htmlwriter.jl +++ b/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) + + occursin(content, "url=./$(version)/") +end + @testset "HTMLWriter" begin @test isdir(HTMLWriter.ASSETS) @test isdir(HTMLWriter.ASSETS_SASS) @@ -104,6 +111,8 @@ 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", @@ -124,6 +133,8 @@ 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, devurl, versions) + verify_redirect_file(redirectfile, "stable") versions = ["v#"] entries, symlinks = expand_versions(tmpdir, versions) @@ -133,6 +144,8 @@ 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, devurl, versions) + verify_redirect_file(redirectfile, "dev") versions = ["v#.#.#"] entries, symlinks = expand_versions(tmpdir, versions) @@ -143,6 +156,8 @@ 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, devurl, versions) + verify_redirect_file(redirectfile, "dev") versions = ["v^", "devel" => "dev", "foobar", "foo" => "bar"] entries, symlinks = @test_logs( @@ -155,6 +170,8 @@ end @test ("devel" => "dev") in symlinks generate_version_file(versionfile, entries) verify_version_file(versionfile, entries) + generate_redirect_file(redirectfile, entries, devurl, versions) + verify_redirect_file(redirectfile, "dev") versions = ["stable" => "v^", "dev" => "stable"] @test_throws ArgumentError expand_versions(tmpdir, versions) From 5e6b7fa9d4280a36dbdd47c586dad8d496fd0d83 Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sun, 25 Jul 2021 16:41:55 +0900 Subject: [PATCH 04/12] remove isnothing for Julia 1.0 --- src/Writers/HTMLWriter.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 9d79302926..4fb8eb7c5c 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -1416,7 +1416,7 @@ function generate_redirect_file(redirectfile::AbstractString, entries, devurl, v version = devurl stable_index = findfirst(v -> last(v)=="v^", versions) - if !isnothing(stable_index) + if stable_index !== nothing stable_version = first(versions[stable_index]) if stable_version in entries version = stable_version From 4e581c6e070ea57c4afd156052a8e107185a6ed8 Mon Sep 17 00:00:00 2001 From: hyrodium Date: Wed, 28 Jul 2021 23:33:19 +0900 Subject: [PATCH 05/12] update redirected destination --- src/Documenter.jl | 2 +- src/Writers/HTMLWriter.jl | 16 +++------------- 2 files changed, 4 insertions(+), 14 deletions(-) diff --git a/src/Documenter.jl b/src/Documenter.jl index 1c59e885ac..6fe490bee9 100644 --- a/src/Documenter.jl +++ b/src/Documenter.jl @@ -609,7 +609,7 @@ function git_push( # 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, devurl, versions) + Writers.HTMLWriter.generate_redirect_file(joinpath(dirname, "index.html"), entries) # generate the symlinks, make sure we don't overwrite devurl cd(dirname) do diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl index 4fb8eb7c5c..6b95da2666 100644 --- a/src/Writers/HTMLWriter.jl +++ b/src/Writers/HTMLWriter.jl @@ -1406,26 +1406,16 @@ function generate_version_file(versionfile::AbstractString, entries, symlinks = end # write redirect file -function generate_redirect_file(redirectfile::AbstractString, entries, devurl, versions) - # If `versions` contains "stable"=>"v^" and `entries` contains "stable", then version="stable". - # In other cases, version="dev". +function generate_redirect_file(redirectfile::AbstractString, entries) + # The link to the redirected destination is same as outdated-warning. (DOCUMENTER_STABLE) comment = "" isfile(redirectfile) && !startswith(read(redirectfile, String), comment) && return - version = devurl - stable_index = findfirst(v -> last(v)=="v^", versions) - if stable_index !== nothing - stable_version = first(versions[stable_index]) - if stable_version in entries - version = stable_version - end - end - open(redirectfile, "w") do buf println(buf, comment) - println(buf, "") + println(buf, "") end end From e40fd6d800397238b68ae77223aac1d6b2d19be2 Mon Sep 17 00:00:00 2001 From: hyrodium Date: Wed, 28 Jul 2021 23:39:20 +0900 Subject: [PATCH 06/12] fix test for generate_redirect_file --- test/htmlwriter.jl | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/htmlwriter.jl b/test/htmlwriter.jl index 26ea48f3f9..cc83ff8e91 100644 --- a/test/htmlwriter.jl +++ b/test/htmlwriter.jl @@ -20,7 +20,7 @@ function verify_redirect_file(redirectfile, version) @test isfile(redirectfile) content = read(redirectfile, String) - occursin(content, "url=./$(version)/") + @test occursin("url=./$(version)/", content) end @testset "HTMLWriter" begin @@ -133,7 +133,7 @@ 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, devurl, versions) + generate_redirect_file(redirectfile, entries) verify_redirect_file(redirectfile, "stable") versions = ["v#"] @@ -144,8 +144,8 @@ 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, devurl, versions) - verify_redirect_file(redirectfile, "dev") + generate_redirect_file(redirectfile, entries) + verify_redirect_file(redirectfile, "v2.1") versions = ["v#.#.#"] entries, symlinks = expand_versions(tmpdir, versions) @@ -156,8 +156,8 @@ 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, devurl, versions) - verify_redirect_file(redirectfile, "dev") + generate_redirect_file(redirectfile, entries) + verify_redirect_file(redirectfile, "v2.1.1") versions = ["v^", "devel" => "dev", "foobar", "foo" => "bar"] entries, symlinks = @test_logs( @@ -170,8 +170,8 @@ end @test ("devel" => "dev") in symlinks generate_version_file(versionfile, entries) verify_version_file(versionfile, entries) - generate_redirect_file(redirectfile, entries, devurl, versions) - verify_redirect_file(redirectfile, "dev") + generate_redirect_file(redirectfile, entries) + verify_redirect_file(redirectfile, "v2.1") versions = ["stable" => "v^", "dev" => "stable"] @test_throws ArgumentError expand_versions(tmpdir, versions) From 6bac04d41a64c863923e572d947309789cc9198e Mon Sep 17 00:00:00 2001 From: hyrodium Date: Fri, 30 Jul 2021 23:56:31 +0900 Subject: [PATCH 07/12] update CHANGELOG.md --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f976b769f0..2568c1d13e 100644 --- a/CHANGELOG.md +++ b/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)) From dd5f1e1aa2fde0c6c7e74c5be6e89680e7e5d5aa Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sat, 31 Jul 2021 00:28:35 +0900 Subject: [PATCH 08/12] add links in CHANGELOG.md --- CHANGELOG.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2568c1d13e..dc5ea39abd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 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]) - +docu ## 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)) @@ -689,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/issue/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 @@ -896,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-1661]: https://github.com/JuliaDocs/Documenter.jl/pull/1657 +[github-1661]: 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 From 0f19ae724d92d6de50a9dff5a630b7020ea1aabf Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sat, 31 Jul 2021 00:47:23 +0900 Subject: [PATCH 09/12] update tests --- test/htmlwriter.jl | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/test/htmlwriter.jl b/test/htmlwriter.jl index cc83ff8e91..f97f12edc1 100644 --- a/test/htmlwriter.jl +++ b/test/htmlwriter.jl @@ -117,13 +117,15 @@ end "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"] @@ -136,6 +138,7 @@ end 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"] @@ -147,6 +150,7 @@ end 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", @@ -159,6 +163,7 @@ end 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\"`"), @@ -173,8 +178,26 @@ end 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. From 959a69ac0f905dca8a359bbd15f41f62b592d84b Mon Sep 17 00:00:00 2001 From: hyrodium Date: Sat, 31 Jul 2021 00:50:06 +0900 Subject: [PATCH 10/12] remove typo --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dc5ea39abd..b23bdc38d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 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]) -docu + ## 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)) From 697576bc222de810cb8f11b6f4b1a165f29c1eab Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Fri, 30 Jul 2021 18:01:02 +0200 Subject: [PATCH 11/12] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b23bdc38d2..7daf8e4d84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -689,7 +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/issue/937 +[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 From eba6ff0b8ce376e3f59aac8419793d58a4d932ae Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Sun, 1 Aug 2021 19:08:34 +1200 Subject: [PATCH 12/12] Update CHANGELOG.md --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7daf8e4d84..37b476e4d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -897,8 +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-1661]: https://github.com/JuliaDocs/Documenter.jl/pull/1657 -[github-1661]: https://github.com/JuliaDocs/Documenter.jl/pull/1658 +[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