Update Documenter compat for version 1.0

Project.toml

@@ -23,7 +23,7 @@ PlutoStaticHTML = "359b1769-a58e-495b-9770-312e911026ad"
 PlutoNotebook = "PlutoStaticHTML"
 
 [compat]
-Documenter = "0.22, 0.23, 0.24, 0.25, 0.26, 0.27"
+Documenter = "0.22, 0.23, 0.24, 0.25, 0.26, 0.27, 1"
 FileIO = "1"
 HTTP = "0.6, 0.7, 0.8, 0.9, 1"
 ImageCore = "0.7, 0.8, 0.9, 0.10"

src/generate.jl

@@ -203,12 +203,6 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
 
         # pipeline: generate postprocess callback function
         postprocess_cb = ()->begin
-            @info "Redirect page URL: redirect docs-edit-link for demos in \"$(source)\" directory."
-            isnothing(templates) || push!(source_files, joinpath(page_root, "index.md"))
-            foreach(source_files) do source_file
-                redirect_link(source_file, source, root, src, build, edit_branch)
-            end
-
             @info "Clean up DemoCards build dir: \"$source\""
             # Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
             Base.Sys.iswindows() && GC.gc()
@@ -426,98 +420,6 @@ function _copy_assets(dest_root::String, src_root::String)
     end
 end
 
-### postprocess
-
-"""
-    redirect_link(src_file, source, root, src, build, edit_branch)
-
-Redirect the "Edit On GitHub" link of generated demo files to its original url, without
-this a 404 error is expected.
-"""
-function redirect_link(source_file, source, root, src, build, edit_branch)
-    build_file = get_build_file(source_file, source, root, build)
-    if !isfile(build_file)
-        @warn "$build_file doesn't exists, skip"
-        return nothing
-    end
-    contents = read(build_file, String)
-
-    if !isfile(source_file)
-        # reach here when user doesn't create a page template index.md
-        # just remove the whole button so that user don't click and get 404
-        new_contents = replace(contents, regex_edit_on_github=>"")
-    else
-        # otherwise, redirect the url links
-        m = match(regex_edit_on_github, contents)
-        isnothing(m) && return nothing
-        build_url = m.captures[1]
-
-        src_url = get_source_url(build_url, source, basename(source_file), src)
-        new_contents = replace(contents, build_url=>src_url)
-    end
-    write(build_file, new_contents)
-end
-
-function get_source_url(build_url, source, cardname, src)
-    # given input:
-    #   - projct_root:          "$REPO/blob/$edit_branch"
-    #   - build_root:           "$projct_root/$docs_root/$src"
-    #   - build_dir:            "$build_root/$prefix/$page/$section/$subsection"
-    #   - build_url:            "$build_dir/$cardfile"
-    # example of build_url:
-    #  "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/src/quickstart/usage_example/julia_demos/2.cover_on_the_fly.md"
-    # we need to generate:
-    #   - src_root:             "$projct_root/$docs_root/$src"
-    #   - src_dir:              "$src_root/$prefix/$page/$section/$subsection"
-    #   - src_url:              "$src_dir/$cardfile"
-    # example of src_url:
-    #   "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/quickstart/usage_example/julia_demos/2.cover_on_the_fly.jl"
-    source = replace(source, Base.Filesystem.path_separator => "/")
-
-    repo, path = strip.(split(build_url, "/blob/"; limit=2), '/')
-    root_to_subsection = replace(splitdir(path)[1], "$(src)/" => ""; count=1)
-    root_to_subsection = replace(root_to_subsection, "/$(basename(source))/" => "/$(source)/"; count=1)
-    src_url = join([repo, "blob", root_to_subsection, cardname], "/")
-
-    return src_url
-end
-
-function get_build_file(source_file, source, root, build)
-    # given inputs:
-    #   - source_file: "$source_root/$prefix/$page/$section/$subsection/$card.md"
-    #   - source:      "$prefix/$page
-    #   - build:       "build"
-    # we need to generate:
-    #   - build_root: "$source_root/$build"
-    #   - build_dir: "$build_root/$page/$section/$subsection
-    #   - build_file: "$build_dir/$card.html" or "$build_dir/$card/index.html"
-
-    sep = Base.Filesystem.path_separator
-    # add trailing / to avoid incorrect substring match
-    source_root = abspath(root, source)
-    build_root = joinpath(root, build)
-    prefix, page = splitdir(source_root)
-
-    source_dir, name = splitdir(source_file)
-    card, ext = splitext(name)
-    _, prefix_to_subsection = split(source_dir, source_root; limit=2)
-    if !isempty(prefix) && prefix_to_subsection != ""
-        # add trailing / to remove leading / for prefix_to_subsection
-        # otherwise, joinpath of two absolute path would simply drop the first one
-        _, prefix_to_subsection = split(prefix_to_subsection, sep; limit=2)
-    end
-    build_dir = joinpath(build_root, page, prefix_to_subsection)
-
-    prettyurls = isdir(joinpath(build_dir, card))
-    # Documenter.HTML behaves differently on prettyurls
-    if prettyurls
-        build_file = joinpath(build_dir, card, "index.html")
-    else
-        build_file = joinpath(build_dir, card * ".html")
-    end
-    return build_file
-end
-
 # modified from https://github.com/fredrikekre/Literate.jl to replace the use of @__NBVIEWER_ROOT_URL__
 function get_nbviewer_root_url(branch)
     if haskey(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL") # Travis CI

src/preview.jl

@@ -107,7 +107,8 @@ function preview_demos(demo_path::String;
                 "Index" => relpath(page_index, src),
                 demos
             ],
-            sitename="DemoCards Preview"
+            sitename="DemoCards Preview",
+            remotes=nothing
         )
 
         demos_cb()

src/types/julia.jl

@@ -150,6 +150,7 @@ function save_democards(card_dir::String,
                         kwargs...)
     isdir(card_dir) || mkpath(card_dir)
     @debug card.path
+    original_card_path = card.path
     cardname = splitext(basename(card.path))[1]
     md_path = joinpath(card_dir, "$(cardname).md")
     nb_path = joinpath(card_dir, "$(cardname).ipynb")
@@ -256,7 +257,7 @@ function save_democards(card_dir::String,
     # @ref syntax: https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@ref-link-1
     header = need_header ? "# [$(card.title)](@id $(card.id))\n" : "\n"
     footer = credit ? julia_footer : "\n"
-    write(md_path, header, body, footer)
+    write(md_path, meta_edit_url(original_card_path), header, body, footer)
 
     # 5. filter out source file
     mktempdir(card_dir) do tmpdir

src/types/markdown.jl

@@ -118,5 +118,5 @@ function save_democards(card_dir::String,
     header = need_header ? "# [$(card.title)](@id $(card.id))\n" : "\n"
 
     footer = credit ? markdown_footer : "\n"
-    write(markdown_path, header, make_badges(card)*"\n\n", body, footer)
+    write(markdown_path, meta_edit_url(card.path), header, make_badges(card)*"\n\n", body, footer)
 end

src/types/page.jl

@@ -160,7 +160,7 @@ function DemoPage(root::String, filter_func=x -> true)::DemoPage
 
     # default template requires a title
     template = load_config(page, "template"; config=config)
-    page.template = template
+    page.template = meta_edit_url(template_file) * template
 
     if haskey(config, "properties")
         properties = config["properties"]::Dict

src/utils.jl

@@ -371,3 +371,18 @@ function input_bool(prompt)
 end
 
 is_pluto_notebook(path::String) = any(occursin.(r"#\s?╔═╡\s?[0-9a-f\-]{36}", readlines(path)))
+
+"""
+    meta_edit_url(path)
+
+helper to add in corrected edit link for markdown files which will be processed by Documenter.jl later
+"""
+function meta_edit_url(path)
+    escaped_path = escape_string(path)
+    return """
+    ```@meta
+    EditURL = "$escaped_path"
+    ```
+
+    """
+end

test/generate.jl

@@ -8,7 +8,7 @@
         @test_reference joinpath("references", "generate_section_$theme.txt") generate(sec, templates) by=ignore_CR
 
         page = DemoPage(joinpath(root, "page", "default"))
-        @test_reference joinpath("references", "generate_page_$theme.txt") generate(page, templates) by=ignore_CR
+        @test_reference joinpath("references", "generate_page_$theme.txt") generate(page, templates) by=ignore_all
     end
 
     abs_root = joinpath(pwd(), root, "page", "default")
@@ -26,7 +26,7 @@
         page_dir = @suppress_err preview_demos(joinpath(root, "page", "hidden"); theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
         # test only one card is shown in index.md
-        @test_reference joinpath("references", "hidden_index.txt") read(md_index, String)
+        @test_reference joinpath("references", "hidden_index.txt") read(md_index, String) by=ignore_all
 
         # check that assets are still normally generated even if they are hidden from index.md
         @test readdir(page_dir) == ["covers", "index.md", "sec"]

test/preview.jl

@@ -5,7 +5,7 @@
     @testset "page structure" begin
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "page", "template"), theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_page.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_page.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["covers", "index.md", "subsection_1", "subsection_2"]
         @test readdir(joinpath(page_dir, "subsection_2")) == ["card_3.md", "card_4.md"]
@@ -20,7 +20,7 @@
     @testset "section with non page structure" begin
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "preview", "scripts"), theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_sec_nopage.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_sec_nopage.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["assets", "covers", "index.md", "scripts"]
         @test readdir(joinpath(page_dir, "covers")) == ["demo2.svg", "democards_logo.svg"]
@@ -30,7 +30,7 @@
     @testset "section with page structure" begin
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "page", "template", "subsection_2"), theme="grid", require_html=false) 
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_sec_page.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_sec_page.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["covers", "index.md", "subsection_2"]
         @test readdir(joinpath(page_dir, "subsection_2")) == ["card_3.md", "card_4.md"]
@@ -43,7 +43,7 @@
     @testset "file with non page structure" begin
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "preview", "scripts", "demo2.md"), theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_file.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_file.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["assets", "covers", "index.md", "scripts"]
         @test readdir(joinpath(page_dir, "covers")) == ["demo2.svg"]
@@ -52,7 +52,7 @@
 
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "preview_demo1.jl"), theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_file2.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_file2.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["covers", "index.md", "preview_section"]
         @test readdir(joinpath(page_dir, "covers")) == ["democards_logo.svg"]
@@ -62,7 +62,7 @@
     @testset "file with page structure" begin
         page_dir = @suppress_err preview_demos(joinpath(abs_root, "page", "template", "subsection_2", "card_3.md"), theme="grid", require_html=false)
         md_index = joinpath(page_dir, "index.md")
-        @test_reference joinpath("references", "preview", "index_file_page.md") read(md_index, String) by=ignore_CR
+        @test_reference joinpath("references", "preview", "index_file_page.md") read(md_index, String) by=ignore_all
 
         @test readdir(page_dir) == ["covers", "index.md", "subsection_2"]
         @test readdir(joinpath(page_dir, "subsection_2")) == ["card_3.md"]

test/references/cards/julia_md.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/card/julia/title_7.jl"
+```
+
 # [Custom Title](@id custom_id)
 
 [![Source code](https://img.shields.io/badge/download-julia-brightgreen.svg)](title_7.jl) ![compat](https://img.shields.io/badge/julia-1.2.3-blue.svg) ![Author](https://img.shields.io/badge/Author-Jane%20Doe-blue) ![Author](https://img.shields.io/badge/Author-John%20Roe-blue) ![Update time](https://img.shields.io/date/1580428800)

test/references/cards/markdown.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/card/markdown/title_6.md"
+```
+
 # [Custom Title](@id custom_id)
 ![Author](https://img.shields.io/badge/Author-Jane%20Doe-blue) ![Author](https://img.shields.io/badge/Author-John%20Roe-blue) ![Update time](https://img.shields.io/date/1580428800)
 

test/references/generate_page_grid.txt

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "assets/page/default/index.md"
+```
+
 # Default
 
 # Subsection 1

test/references/hidden_index.txt

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/hidden/index.md"
+```
+
 # Hidden
 
 # Sec

test/references/preview/index_file.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/preview/index.md"
+```
+
 # Preview
 
 # Scripts

test/references/preview/index_file2.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/preview_page/index.md"
+```
+
 # Preview page
 
 # Preview section

test/references/preview/index_file_page.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/template/template.md"
+```
+
 # Template
 
 # Subsection 2

test/references/preview/index_page.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/template/template.md"
+```
+
 # [Custom Title](@id custom_id)
 
 This is the content of the template

test/references/preview/index_sec_nopage.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/preview/index.md"
+```
+
 # Preview
 
 # Scripts

test/references/preview/index_sec_page.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "/tmp/jl_MynnRG/template/template.md"
+```
+
 # Template
 
 # Subsection 2

test/testutils.jl

@@ -1,3 +1,34 @@
+"""
+This function combines `ignore_CR` with ignoring difference between `ref` and
+`actual` resulting from blank lines.
+"""
+ignore_all(ref::AbstractString, actual::AbstractString) = isequal(_ignore_all(ref), _ignore_all(actual))
+
+_ignore_all(x::AbstractString) = _ignore_tempdir(_ignore_blank_line_and_CR(_ignore_CR(x)))
+
+const edit_url_re = r"EditURL = \"(.*)\""
+
+function _ignore_tempdir(doc::AbstractString)
+    path_match = match(edit_url_re, doc)
+    if path_match === nothing
+        return doc
+    end
+    path = unescape_string(path_match[1])
+    if !startswith(path, "/") && match(r"^[A-Z]:", path) === nothing
+        # all we need to do is normalise the path separator
+        norm_dir = replace(path, "\\" => "/")
+    else
+        # we need to remove the tempdir part of the path
+        bits = split(replace(path, "\\" => "/"), "/")
+        tmp_dir = findlast(x -> startswith(x, "jl_"), bits)
+        if tmp_dir === nothing
+            error("Cannot find tempdir in $path")
+        end
+        norm_dir = "/TEMPDIR/" * join(bits[end+1:end], "/")
+    end
+    return replace(doc, edit_url_re => "EditURL = \"$norm_dir\"")
+end
+
 """
 This function combines `ignore_CR` with ignoring difference between `ref` and
 `actual` resulting from blank lines.

test/types/julia.jl

@@ -118,8 +118,8 @@
                 replace(contents, r"\[!\[notebook\]\(.*\)\]\(.*\.ipynb\) " => "")
             end
             isempty(DemoCards.get_nbviewer_root_url("master")) || println(read(joinpath(card_dir, "title_7.md"), String)) # for debug usage
-            @test_reference joinpath(test_root, "references", "cards", "julia_md.md") strip_notebook(read(joinpath(card_dir, "title_7.md"), String)) by=ignore_CR
-            @test_reference joinpath(test_root, "references", "cards", "julia_src.jl") read(joinpath(card_dir, "title_7.jl"), String) by=ignore_blank_line_and_CR
+            @test_reference joinpath(test_root, "references", "cards", "julia_md.md") strip_notebook(read(joinpath(card_dir, "title_7.md"), String)) by=ignore_all
+            @test_reference joinpath(test_root, "references", "cards", "julia_src.jl") read(joinpath(card_dir, "title_7.jl"), String) by=ignore_all
             @test isfile(joinpath(card_dir, "title_7.ipynb"))
 
             # check if notebook keyword actually affects the generation

test/types/markdown.jl

@@ -80,7 +80,7 @@
         @testset "generate" begin
             page_dir = @suppress_err preview_demos("title_6.md", theme="grid", require_html=false)
             card_path = joinpath(page_dir, "markdown", "title_6.md")
-            @test_reference joinpath(test_root, "references", "cards", "markdown.md") read(card_path, String) by=ignore_CR
+            @test_reference joinpath(test_root, "references", "cards", "markdown.md") read(card_path, String) by=ignore_all
         end
     end
 end