add LocalRemoteCard

Author: johnnychen94

src/DemoCards.jl

@@ -35,6 +35,7 @@ include("compat.jl")
 include("types/card.jl")
 include("types/section.jl")
 include("types/page.jl")
+include("remote.jl")
 
 include("utils.jl")
 include("show.jl")

src/generate.jl

@@ -150,6 +150,8 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
             )
         end
     else
+        # For themes that requires an index page
+        # This will not generate a multi-level structure in the sidebar
         out_path = joinpath(relative_root, "index.md")
     end
 
@@ -199,6 +201,9 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
             @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
+                # LocalRemoteCard is a virtual placeholder and does not exist here
+                isfile(source_file) && return
+                # only redirect to "real" files
                 redirect_link(source_file, source, root, src, build, edit_branch)
             end
 
@@ -239,14 +244,14 @@ function generate(page::DemoPage, templates)
     Mustache.render(page.template, items)
 end
 
-function generate(cards::AbstractVector{<:AbstractDemoCard}, template)
+function generate(cards::AbstractVector{<:Union{AbstractDemoCard, LocalRemoteCard}}, template)
     # for those hidden cards, only generate the necessary assets and files, but don't add them into
     # the index.md page
-    foreach(filter(x->x.hidden, cards)) do x
+    foreach(filter(ishidden, cards)) do x
         generate(x, template)
     end
 
-    mapreduce(*, filter(x->!x.hidden, cards); init="") do x
+    mapreduce(*, filter(x->!ishidden(x), cards); init="") do x
         generate(x, template)
     end
 end
@@ -313,7 +318,7 @@ function save_cover(path::String, sec::DemoSection)
 end
 
 """
-    save_cover(path::String, card::AbstractDemoCard)
+    save_cover(path::String, card)
 
 process the cover image and save it.
 """
@@ -348,7 +353,7 @@ function save_cover(path::String, card::AbstractDemoCard)
     end
 end
 
-function get_covername(card::AbstractDemoCard)
+function get_covername(card)
     isnothing(card.cover) && return nothing
     is_remote_url(card.cover) && return card.cover
 

src/preview.jl

@@ -55,6 +55,7 @@ function preview_demos(demo_path::String;
 
     page_dir = generate_or_copy_pagedir(demo_path, build_dir)
     copy_assets_and_configs(page_dir, build_dir)
+    rewrite_localremote_path(page_dir, build_dir)
 
     cd(build_dir) do
         page = @suppress_err DemoPage(page_dir)
@@ -208,7 +209,12 @@ function copy_assets_and_configs(src_page_dir, dst_build_dir=pwd())
             config = JSON.parsefile(src_config_path)
             config_dir = dirname(dst_config_path)
             if haskey(config, "order")
-                order =  [x for x in config["order"] if x in readdir(config_dir)]
+                files = readdir(config_dir)
+                remote_files = keys(get(config, "remote", Dict()))
+                order = filter(config["order"]) do x
+                    x in files || x in remote_files
+                end
+
                 if isempty(order)
                     delete!(config, "order")
                 else
@@ -226,3 +232,28 @@ function copy_assets_and_configs(src_page_dir, dst_build_dir=pwd())
         end
     end
 end
+
+function rewrite_localremote_path(page_dir, build_dir)
+    # To support relpath for LocalRemoteCard, we have to
+    # eagerly rewrite the relpath with abspath so that
+    # later build can correctly find the remote filepath.
+    # This only affects LocalRemoteCard with relpath.
+
+    page = @suppress_err DemoPage(page_dir)
+    walkpage(page) do dir, card
+        if card isa LocalRemoteCard
+            # find out the corresponding config file, and rewrite the remote entry
+            # with abspath
+            build_carddir = joinpath(build_dir, basename(page_dir), relpath(dir, page_dir))
+            src_config_path = joinpath(build_carddir, config_filename)
+
+            config = JSON.parsefile(src_config_path)
+            config["remote"][card.name] = card.path
+
+            open(src_config_path, "w") do io
+                JSON.print(io, config)
+            end
+        end
+    end
+
+end

src/remote.jl

@@ -0,0 +1,68 @@
+abstract type AbstractRemotePath end
+
+#####
+# LocalRemote
+#####
+struct LocalRemoteCard{T<:AbstractDemoCard} <: AbstractRemotePath
+    name::String
+    path::String
+    item::T
+    function LocalRemoteCard(name::String, path::String, item::T) where T<:AbstractDemoCard
+        basename(name) == name || throw(ArgumentError("`name` should not be a path, instead it is: $name"))
+        isfile(path) || throw(ArgumentError("file $path does not exist."))
+        new{T}(name, path, item)
+    end
+end
+
+ishidden(card::LocalRemoteCard) = ishidden(card.item)
+
+function Base.basename(card::LocalRemoteCard{T}) where T
+    name, ext = splitext(card.name)
+    if isempty(ext)
+        if T <: MarkdownDemoCard
+            ext = ".md"
+        elseif T <: JuliaDemoCard
+            ext = ".jl"
+        else
+            throw(ArgumentError("Unknown card type $T"))
+        end
+    end
+    return name * ext
+end
+
+function Base.show(io::IO, card::LocalRemoteCard)
+    print(io, basename(card), " => ", card.path)
+end
+
+function generate(card::LocalRemoteCard, template)
+    with_tempcard(card) do tempcard
+        generate(tempcard, template)
+    end
+end
+function save_democards(card_dir::String, card::LocalRemoteCard; kwargs...)
+    dst = joinpath(card_dir, basename(card))
+    isfile(dst) && throw(ArgumentError("file $dst already exists."))
+
+    with_tempcard(card) do tempcard
+        save_democards(card_dir, tempcard; kwargs...)
+    end
+end
+
+function save_cover(path::String, card::LocalRemoteCard)
+    with_tempcard(card) do tempcard
+        save_cover(path, tempcard)
+    end
+end
+
+# TODO: this file copy is not very necessary, and it get called many times
+function with_tempcard(f, card)
+    mktempdir() do dir
+        # copy and rename file so that generated files are correctly handled
+        # For example:
+        #   "cardname" => "path/to/sourcefile.jl"
+        # Later workflow uses "cardname.md" instead of "sourcefile.md"
+        tmpfile = joinpath(dir, basename(card))
+        cp(card.path, tmpfile)
+        f(democard(tmpfile))
+    end
+end

src/types/julia.jl

@@ -244,3 +244,5 @@ function make_badges(card::JuliaDemoCard; src, card_dir, nbviewer_root_url, proj
 
     join(badges, " ")
 end
+
+ishidden(x::JuliaDemoCard) = x.hidden

src/types/markdown.jl

@@ -133,3 +133,5 @@ function save_democards(card_dir::String,
     footer = credit ? markdown_footer : "\n"
     write(markdown_path, header, make_badges(card)*"\n\n", body, footer)
 end
+
+ishidden(x::MarkdownDemoCard) = x.hidden

src/types/section.jl

@@ -97,38 +97,63 @@ function DemoSection(root::String)::DemoSection
     # For files that `democard` fails to recognized, dummy
     # `UnmatchedCard` will be generated. Currently, we only
     # throw warnings for it.
-    cards = map(democard, card_paths)
+    cards = Union{AbstractDemoCard, LocalRemoteCard}[democard(x) for x in card_paths]
     unmatches = filter(cards) do x
         x isa UnmatchedCard
     end
     if !isempty(unmatches)
         msg = join(map(basename, unmatches), "\", \"")
         @warn "skip unmatched file: \"$msg\"" section_dir=root
     end
+
     cards = filter!(cards) do x
         !(x isa UnmatchedCard)
     end
 
-    section = DemoSection(root,
-                          cards,
-                          map(DemoSection, section_paths),
-                          "",
-                          "")
-
-    ordered_paths = joinpath.(root, load_config(section, "order"; config=config))
-    if !isempty(section.cards)
-        cards = map(democard, ordered_paths)
-        subsections = []
-    else
-        cards = []
-        subsections = map(DemoSection, ordered_paths)
+    if haskey(config, "remote")
+        remote_cards = LocalRemoteCard[]
+        for (cardname, cardpath) in config["remote"]
+            # if possible, store the abspath
+            cardpath = isabspath(cardpath) ? cardpath : normpath(joinpath(root, cardpath))
+            push!(remote_cards, LocalRemoteCard(cardname, cardpath, democard(cardpath)))
+        end
+        append!(cards, remote_cards)
     end
 
+    subsections = map(DemoSection, section_paths)
+    section = DemoSection(root, cards, subsections, "", "")
+    cards, subsections = sort_by_order(section, config)
+
     title = load_config(section, "title"; config=config)
     description = load_config(section, "description"; config=config)
     DemoSection(root, cards, subsections, title, description)
 end
 
+function sort_by_order(sec::DemoSection, config)
+    cards = sec.cards
+    subsections = sec.subsections
+
+    ordered_paths = load_config(sec, "order"; config=config)
+    if !isempty(sec.cards)
+        indices = map(ordered_paths) do ref
+            findfirst(cards) do card
+                basename(card) == ref
+            end
+        end
+        cards = cards[indices]
+        subsections = []
+    else
+        indices = map(ordered_paths) do ref
+            findfirst(subsections) do sec
+                basename(sec) == ref
+            end
+        end
+        subsections = subsections[indices]
+        cards = []
+    end
+
+    return cards, subsections
+end
 
 function load_config(sec::DemoSection, key; config=Dict())
     if isempty(config)

test/assets/remote/remote_card_mixed/config.json

@@ -0,0 +1,6 @@
+{
+    "remote": {
+        "julia_card": "../../card/julia/title_1.jl",
+        "markdown_card": "../../card/markdown/title_3.md"
+    }
+}

test/assets/remote/remote_card_mixed/title_2.md

@@ -0,0 +1,3 @@
+# [Custom Title 2](@id custom_id_2)
+
+This is the content

test/assets/remote/remote_card_mixed_order/config.json

@@ -0,0 +1,11 @@
+{
+    "remote": {
+        "julia_card.jl": "../../card/julia/title_1.jl",
+        "markdown_card.md": "../../card/markdown/title_3.md"
+    },
+    "order": [
+        "julia_card.jl",
+        "markdown_card.md",
+        "title_2.md"
+    ]
+}