Merge pull request #65 from johnnychen94/jc/properties

add card properties: author, date, julia

Author: johnnychen94

Project.toml

@@ -4,8 +4,10 @@ authors = ["Johnny Chen <[email protected]>"]
 version = "0.2.3"
 
 [deps]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
@@ -16,6 +18,7 @@ YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 [compat]
 Documenter = "0.22, 0.23, 0.24, 0.25"
 FileIO = "1"
+HTTP = "0.6, 0.7, 0.8"
 ImageCore = "0.7, 0.8"
 JSON = "0.20, 0.21"
 Literate = "2"
@@ -25,12 +28,11 @@ YAML = "0.3, 0.4"
 julia = "1"
 
 [extras]
-HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
 ReferenceTests = "324d217c-45ce-50fc-942e-d289b448e8cf"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [targets]
-test = ["HTTP", "ImageMagick", "ImageShow", "ReferenceTests", "Test", "TestImages"]
+test = ["ImageMagick", "ImageShow", "ReferenceTests", "Test", "TestImages"]

docs/quickstart/usage_example/basics/configure_card.md

@@ -2,6 +2,8 @@
 title: Configure your card
 cover: assets/logo.svg
 id: configure_your_card
+author: Johnny Chen
+date: 2020-09-13
 description: This demo show you how to pass additional meta info of card to DemoCards.jl
 ---
 
@@ -14,15 +16,26 @@ frontmatter:
 title: Configure your card
 cover: assets/democards.png
 id: configure_your_card
+author: Johnny Chen
+date: 2020-09-13
 description: This demo show you how to pass additional meta info of card to DemoCards.jl
 
 ---
 ```
 
-Of course, you have to make sure the `---` flag shows at the first line of the markdown file,
-otherwise DemoCards would just read them as normal contents.
+!!! tip
+    All these YAML configs are optional. If specified, it has higher priority over the meta info
+    extracted from the demo contents. For example, if you don't like the inferred demo title, then
+    specify one explicitly in the YAML frontmatter.
 
-There are two valid `cover` options:
+    Of course, you have to make sure the `---` flag shows at the first line of the markdown file,
+    otherwise DemoCards would just read them as normal contents.
 
-* a local file specified by relative path to the current file, or,
-* an image file specified by http(s) URL (e.g, `https://johnnychen94.github.io/DemoCards.jl/dev/assets/logo.svg`)
+The rules are simple:
+
+* `author` and `date` badges will only be added if you configure them.
+* If there are multiple authors, they could be splitted by semicolon `;`. For example, `author:
+  Jane Doe; John Roe` would generate two author badges.
+* there are two valid `cover` options:
+  * a local file specified by relative path to the current file, or,
+  * an image file specified by http(s) URL.

docs/quickstart/usage_example/julia_demos/1.julia_demo.jl

@@ -5,6 +5,9 @@
 # ---
 # title: Write your demo in julia
 # cover: assets/literate.png
+# date: 2020-09-13
+# author: Johnny Chen
+# julia: 1.0.1
 # description: This demo shows you how to write your demo in julia
 # ---
 
@@ -37,10 +40,18 @@ img = testimage("lena")
 # # title: <title>
 # # cover: <cover>
 # # id: <id>
+# # date: 2020-09-13
+# # author: Johnny Chen
+# # julia: 1.3
 # # description: <description>
 # # ---
 # ```
 
+# Julia format demos accept one extra frontmatter config: `julia`. It allows you to specify the
+# compat version of your demo. `DemoCards` would 1) throw a warning if your demos are generated
+# using a lower version of Julia 2) insert a compat version badge. The warning is something like
+# "The running Julia version `1.0.5` is older than the declared compatible version `1.3.0`."
+
 # You should be careful about the leading whitespaces after the first #. Frontmatter as weird as the
 # following is not guaranteed to work and it is very likely to hit a YAML parsing error.
 

src/DemoCards.jl

@@ -1,13 +1,21 @@
 module DemoCards
 
 import Base: basename
+using Dates
 using Mustache
 using Literate
 using ImageCore
 using FileIO, JSON, YAML
 using Suppressor # suppress log generated by 3rd party tools, e.g., Literate
+import HTTP
 using Documenter
 
+const JULIA_COMPAT = let regex=r"julia\s*=\s*\"([\d\.]*)\""
+    lines = filter(readlines(normpath(@__DIR__, "..", "Project.toml"))) do line
+        occursin(regex, line)
+    end
+    VersionNumber(match(regex, lines[1]).captures[1])
+end
 const config_filename = "config.json"
 const template_filename = "index.md"
 # directly copy these folders without processing

src/types/card.jl

@@ -51,7 +51,6 @@ function load_config(card::T, key) where T <: AbstractDemoCard
     config = parse(card)
 
     if key == "cover"
-        root = dirname(card.path)
         haskey(config, key) || return nothing
 
         cover_path = config[key]
@@ -68,11 +67,35 @@ function load_config(card::T, key) where T <: AbstractDemoCard
         return get(config, key, card.title)
     elseif key == "hidden"
         return get(config, key, false)
+    elseif key == "author"
+        return get(config, key, "")
+    elseif key == "date"
+        return DateTime(get(config, key, DateTime(0)))
+    elseif key == "julia"
+        version = get(config, key, JULIA_COMPAT)
+        return version isa VersionNumber ? version : VersionNumber(string(version))
     else
         throw(ArgumentError("Unrecognized key $(key) for $(T)"))
     end
 end
 
+function make_badges(card::AbstractDemoCard)
+    badges = []
+    if !isempty(card.author)
+        for author in split(card.author, ';')
+            # TODO: also split on "and"
+            isempty(author) && continue
+            author_str = HTTP.escapeuri(strip(author))
+            push!(badges, "![Author](https://img.shields.io/badge/Author-$(author_str)-blue)")
+        end
+    end
+    if card.date != DateTime(0)
+        date_str = string(round(Int, datetime2unix(card.date)))
+        push!(badges, "![Update time](https://img.shields.io/date/$(date_str))")
+    end
+    isempty(badges) ? "" : join(badges, " ")
+end
+
 
 ### load concrete implementations
 

src/types/julia.jl

@@ -27,7 +27,11 @@ Besides `path`, this struct has some other fields:
 * `cover`: path to the cover image
 * `id`: cross-reference id
 * `title`: one-line description of the demo card
+* `author`: author(s) of this demo.
+* `date`: the update date of this demo.
 * `description`: multi-line description of the demo card
+* `julia`: Julia version compatibility
+* `hidden`: whether this card is shown in the generated index page
 
 # Configuration
 
@@ -38,6 +42,9 @@ Supported items are:
 * `description`: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses `title`.
 * `id`: specify the `id` tag for cross-references. By default it's infered from the filename, e.g., `simple_demo` from `simple demo.md`.
 * `title`: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
+* `author`: author name. If there are multiple authors, split them with semicolon `;`.
+* `date`: any string contents that can be passed to `Dates.DateTime`. For example, `2020-09-13`.
+* `julia`: Julia version compatibility. Any string that can be converted to `VersionNumber`
 * `hidden`: whether this card is shown in the layout of index page. The default value is `false`.
 
 An example of the front matter (note the leading `#`):
@@ -47,7 +54,11 @@ An example of the front matter (note the leading `#`):
 # title: passing extra information
 # cover: cover.png
 # id: non_ambiguious_id
-# description: this demo shows how you can pass extra demo information to DemoCards package.
+# author: Jane Doe; John Roe
+# date: 2020-01-31
+# description: this demo shows how you can pass extra demo information to DemoCards package. All these are optional.
+# julia: 1.0
+# hidden: false
 # ---
 ```
 
@@ -59,15 +70,21 @@ mutable struct JuliaDemoCard <: AbstractDemoCard
     id::String
     title::String
     description::String
+    author::String
+    date::DateTime
+    julia::VersionNumber
     hidden::Bool
 end
 
 function JuliaDemoCard(path::String)::JuliaDemoCard
     # first consturct an incomplete democard, and then load the config
-    card = JuliaDemoCard(path, "", "", "", "", false)
+    card = JuliaDemoCard(path, "", "", "", "", "", DateTime(0), JULIA_COMPAT, false)
 
     card.cover = load_config(card, "cover")
     card.title = load_config(card, "title")
+    card.date = load_config(card, "date")
+    card.author = load_config(card, "author")
+    card.julia = load_config(card, "julia")
     # default id requires a title
     card.id    = load_config(card, "id")
     # default description requires a title
@@ -106,6 +123,11 @@ function save_democards(card_dir::String,
     nb_path = joinpath(card_dir, "$(cardname).ipynb")
     src_path = joinpath(card_dir, "$(cardname).jl")
 
+    if VERSION < card.julia
+        # It may work, it may not work; I hope it would work.
+        @warn "The running Julia version `$(VERSION)` is older than the declared compatible version `$(card.julia)`. You might need to upgrade your Julia."
+    end
+
     # 1. generating assets
     cp(card.path, src_path; force=true)
     cd(card_dir) do
@@ -141,21 +163,8 @@ function save_democards(card_dir::String,
     isempty(strip(src_header)) || (src_header *= "\n\n")
 
     # insert header badge
-    header = "#md # [![]($download_badge)]($(cardname).jl)"
-    if !isempty(nbviewer_root_url)
-        # reach here in CI environment
-
-        # remove root/src prefix
-        nbviewer_folder = relpath(card_dir, "$project_dir/$src")
-        nbviewer_url = "$(nbviewer_root_url)/$(nbviewer_folder)/$(cardname).ipynb"
-    else
-        # local build
-        nbviewer_url = "$(cardname).ipynb"
-    end
-    header *= " [![]($nbviewer_badge)]($nbviewer_url)"
-    header *= "\n\n"
-
-    write(src_path, header, body)
+    badges = make_badges(card; src=src, card_dir=card_dir, nbviewer_root_url=nbviewer_root_url, project_dir=project_dir) * "\n\n"
+    write(src_path, badges, body)
 
     # 2. notebook
     try
@@ -185,3 +194,28 @@ function save_democards(card_dir::String,
         write(src_path, src_header, read(joinpath(tmpdir, basename(src_path)), String))
     end
 end
+
+function make_badges(card::JuliaDemoCard; src, card_dir, nbviewer_root_url, project_dir)
+    cardname = splitext(basename(card.path))[1]
+    badges = ["#md #"]
+    push!(badges, "[![Source code]($download_badge)]($(cardname).jl)")
+
+    if !isempty(nbviewer_root_url)
+        # Note: this is only reachable in CI environment
+        nbviewer_folder = normpath(relpath(card_dir, "$project_dir/$src"))
+        nbviewer_url = replace("$(nbviewer_root_url)/$(nbviewer_folder)/$(cardname).ipynb", Base.Filesystem.path_separator=>'/')
+    else
+        nbviewer_url = "$(cardname).ipynb"
+    end
+    push!(badges, "[![notebook]($nbviewer_badge)]($nbviewer_url)")
+    if card.julia != JULIA_COMPAT
+        # It might be over verbose to insert a compat badge for every julia card, only add one for
+        # cards that users should care about
+        # Question: Is this too conservative?
+        push!(badges, "![compat](https://img.shields.io/badge/julia-$(card.julia)-blue.svg)")
+    end
+
+    push!(badges, invoke(make_badges, Tuple{AbstractDemoCard}, card))
+
+    join(badges, " ")
+end

src/types/markdown.jl

@@ -24,7 +24,10 @@ Besides `path`, this struct has some other fields:
 * `cover`: path to the cover image
 * `id`: cross-reference id
 * `title`: one-line description of the demo card
+* `author`: author(s) of this demo.
+* `date`: the update date of this demo.
 * `description`: multi-line description of the demo card
+* `hidden`: whether this card is shown in the generated index page
 
 # Configuration
 
@@ -35,6 +38,8 @@ Supported items are:
 * `description`: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses `title`.
 * `id`: specify the `id` tag for cross-references. By default it's infered from the filename, e.g., `simple_demo` from `simple demo.md`.
 * `title`: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
+* `author`: author name. If there are multiple authors, split them with semicolon `;`.
+* `date`: any string contents that can be passed to `Dates.DateTime`. For example, `2020-09-13`.
 * `hidden`: whether this card is shown in the layout of index page. The default value is `false`.
 
 An example of the front matter:
@@ -44,7 +49,10 @@ An example of the front matter:
 title: passing extra information
 cover: cover.png
 id: non_ambiguious_id
-description: this demo shows how you can pass extra demo information to DemoCards package.
+author: Jane Doe; John Roe
+date: 2020-01-31
+description: this demo shows how you can pass extra demo information to DemoCards package. All these are optional.
+hidden: false
 ---
 ```
 
@@ -56,15 +64,25 @@ mutable struct MarkdownDemoCard <: AbstractDemoCard
     id::String
     title::String
     description::String
+    author::String
+    date::DateTime
     hidden::Bool
 end
 
 function MarkdownDemoCard(path::String)::MarkdownDemoCard
     # first consturct an incomplete democard, and then load the config
-    card = MarkdownDemoCard(path, "", "", "", "", false)
+    card = MarkdownDemoCard(path, "", "", "", "", "", DateTime(0), false)
 
     card.cover = load_config(card, "cover")
     card.title = load_config(card, "title")
+    card.date = load_config(card, "date")
+    card.author = load_config(card, "author")
+
+    # Unlike JuliaDemoCard, Markdown card doesn't accept `julia` compat field. This is because we
+    # generally don't know the markdown processing backend. It might be Documenter, but who knows.
+    # More generally, any badges can just be manually added by demo writter, if they want.
+    # `date` and `author` fields are added just for convinience.
+
     # default id requires a title
     card.id    = load_config(card, "id")
     # default description requires a title
@@ -97,6 +115,7 @@ function save_democards(card_dir::String,
     need_header = !haskey(config, "title")
     # @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 ? markdown_footer : "\n"
-    write(markdown_path, header, body, footer)
+    write(markdown_path, header, make_badges(card)*"\n\n", body, footer)
 end

src/utils.jl

@@ -197,8 +197,10 @@ function parse(T::Val, card::AbstractDemoCard)
     end
 
     if haskey(config, "cover")
-        config["cover"] = replace(config["cover"],
-                                  r"[/\\]" => Base.Filesystem.path_separator) # windows compatibility
+        if !is_remote_url(config["cover"])
+            config["cover"] = replace(config["cover"],
+                                    r"[/\\]" => Base.Filesystem.path_separator) # windows compatibility
+        end
     end
 
     return config

test/assets/card/julia/title_7.jl

@@ -1,6 +1,10 @@
 #---
 #title: Custom Title
 #id: custom_id
+#author: Jane Doe; John Roe
+#date: 2020-01-31
+#julia: 1.2.3
+#cover: https://juliaimages.org/latest/assets/logo.png
 #---
 
 # This is the content

test/assets/card/julia/version_1.jl

@@ -0,0 +1,3 @@
+#---
+#julia: 1.2.3
+#---