Optionally disable notebook build (#98)

Author: johnnychen94

docs/quickstart/usage_example/basics/configure_sec_and_page.md

@@ -44,3 +44,45 @@ There are three possible options for `theme`:
 * `"list"`: a list like index page.
 
 You can check the "Theme Gallery" to see how different themes look like.
+
+
+## [Override default values with properties](@ref page_sec_properties)
+
+Another item that could be useful is `properties`, it is written as a dictionary-like format, and
+provides a way to override some default values. Properties can be configured at any level and it
+follows very simple rules:
+
+- Properties at a higher level item can be propagated into lower level items
+- Properties at lower level items are of higher priority
+
+
+```text
+example_page/
+├── config.json
+├── sec1
+│   ├── config.json
+│   ├── demo1.jl
+│   ├── demo2.jl
+│   └── demo3.md
+└── sec2
+    ├── demo4.jl
+    └── demo5.jl
+```
+
+For example, in the above folder structure, if we configure `example_page/config.json` with
+
+```json
+{
+    "properties":{
+        "notebook": "false"
+    }
+}
+```
+
+Then all julia demos will not generate jupyter notebook unless it's override somewhere in the lower
+level, e.g, `sec1/config.json` or `demo1.jl`.
+
+
+Only a subset of demo entries support the property propagation, currently supported items are:
+
+* Julia files: `notebook` allows you to enable/disable the jupyter notebook generation.

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

@@ -20,6 +20,14 @@
 # 4. jupyter notebook file
 #
 # Links to nbviewer and source files are provided as well.
+
+# !!! note
+#     This entails every source file being executed three times: 1) asset generation, 2) notebook
+#     generation, and 3) Documenter HTML generation. If the generation time is too long for your
+#     application, you could then choose to write your demo in markdown format. Or you can disable
+#     the notebook generation via the `notebook` keyword in your demos, this helps reduce the
+#     runtime to 2x.
+
 #
 # The conversions from source demo files to `.jl`, `.md` and `.ipynb` files are mainly handled by
 # [`Literate.jl`](https://github.com/fredrikekre/Literate.jl). The syntax to control/filter the
@@ -50,7 +58,7 @@ img = testimage("lena")
 # ```
 
 # In addition to the keywords supported by markdown files, Julia format demos accept one extra
-# frontmatter config: `julia`. It allows you to specify the compat version of your demo. With this,
+# frontmatter keyword: `julia`. It allows you to specify the compat version of your demo. With this,
 # `DemoCards` would:
 #
 #   - throw a warning if your demos are generated using a lower version of Julia
@@ -59,6 +67,11 @@ img = testimage("lena")
 # The warning is something like "The running Julia version `1.0.5` is older than the declared
 # compatible version `1.3.0`."
 
+# Another extra keyword is `notebook`, it allows you to control whether you needs to generate
+# jupyter notebook `.ipynb` for the demo. The valid values are `true` and `false`. See also
+# [Override default values with properties](@id page_sec_properties) on how to disable all notebook
+# generation via the properties entry.
+
 # !!! warning
 #     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/generate.jl

@@ -232,46 +232,49 @@ generate(io::IO, page::DemoPage, args...) = write(io, generate(page, args...))
 
 
 function generate(page::DemoPage, templates)
-    items = Dict("democards" => generate(page.sections, templates))
+    items = Dict("democards" => generate(page.sections, templates; properties=page.properties))
     Mustache.render(page.template, items)
 end
 
-function generate(cards::AbstractVector{<:AbstractDemoCard}, template)
+function generate(cards::AbstractVector{<:AbstractDemoCard}, template; properties=Dict{String, Any}())
     # 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
-        generate(x, template)
+        generate(x, template; properties=properties)
     end
 
     mapreduce(*, filter(x->!x.hidden, cards); init="") do x
-        generate(x, template)
+        generate(x, template; properties=properties)
     end
 end
 
-function generate(secs::AbstractVector{DemoSection}, templates; level=1)
+function generate(secs::AbstractVector{DemoSection}, templates; level=1, properties=Dict{String, Any}())
     mapreduce(*, secs; init="") do x
-        generate(x, templates;level=level)
+        properties = merge(properties, x.properties) # sec.properties has higher priority
+        generate(x, templates; level=level, properties=properties)
     end
 end
 
-function generate(sec::DemoSection, templates; level=1)
+function generate(sec::DemoSection, templates; level=1, properties=Dict{String, Any}())
     header = repeat("#", level) * " " * sec.title * "\n"
     footer = "\n"
+    properties = merge(properties, sec.properties) # sec.properties has higher priority
+
     # either cards or subsections are empty
     # recursively generate the page contents
     if isempty(sec.cards)
-        body = generate(sec.subsections, templates; level=level+1)
+        body = generate(sec.subsections, templates; level=level+1, properties=properties)
     else
         items = Dict(
-            "cards" => generate(sec.cards, templates["card"]),
+            "cards" => generate(sec.cards, templates["card"], properties=properties),
             "description" => sec.description
         )
         body = Mustache.render(templates["section"], items)
     end
     header * body * footer
 end
 
-function generate(card::AbstractDemoCard, template)
+function generate(card::AbstractDemoCard, template; properties=Dict{String, Any})
     covername = get_covername(card)
 
     if isnothing(covername)
@@ -287,7 +290,7 @@ function generate(card::AbstractDemoCard, template)
     if length(card.description) >= cut_idx
         # cut descriptions into ~500 characters
         offset = findfirst(' ', description[cut_idx:end])
-        offset == nothing && (offset = 0)
+        offset === nothing && (offset = 0)
         offset = cut_idx + offset - 2
         description = description[1:cut_idx] * "..."
     end
@@ -365,13 +368,14 @@ get_logopath() = joinpath(pkgdir(DemoCards), "assets", "democards_logo.svg")
 recursively process and save source demo file
 """
 function save_democards(root::String, page::DemoPage; kwargs...)
-    save_democards.(root, page.sections; kwargs...)
+    save_democards.(root, page.sections; properties=page.properties, kwargs...)
 end
-function save_democards(root::String, sec::DemoSection; kwargs...)
+function save_democards(root::String, sec::DemoSection; properties, kwargs...)
+    properties = merge(properties, sec.properties) # sec.properties has higher priority
     save_democards.(joinpath(root, basename(sec.root)), sec.subsections;
-                    kwargs...)
+                    properties=properties, kwargs...)
     save_democards.(joinpath(root, basename(sec.root)), sec.cards;
-                    kwargs...)
+                    properties=properties, kwargs...)
 end
 
 ### copy assets

src/types/julia.jl

@@ -32,6 +32,7 @@ Besides `path`, this struct has some other fields:
 * `description`: multi-line description of the demo card
 * `julia`: Julia version compatibility
 * `hidden`: whether this card is shown in the generated index page
+* `notebook`: enable or disable the jupyter notebook generation. Valid values are `true` or `false`.
 
 # Configuration
 
@@ -74,11 +75,12 @@ mutable struct JuliaDemoCard <: AbstractDemoCard
     date::DateTime
     julia::VersionNumber
     hidden::Bool
+    notebook::Union{Nothing, Bool}
 end
 
 function JuliaDemoCard(path::String)::JuliaDemoCard
     # first consturct an incomplete democard, and then load the config
-    card = JuliaDemoCard(path, "", "", "", "", "", DateTime(0), JULIA_COMPAT, false)
+    card = JuliaDemoCard(path, "", "", "", "", "", DateTime(0), JULIA_COMPAT, false, nothing)
 
     config = parse(card)
     card.cover = load_config(card, "cover"; config=config)
@@ -91,6 +93,24 @@ function JuliaDemoCard(path::String)::JuliaDemoCard
     # default description requires a title
     card.description = load_config(card, "description"; config=config)
     card.hidden = load_config(card, "hidden"; config=config)
+
+    # Because we want bottom-level cards configuration to have higher priority, figuring
+    # out the default `notebook` option needs a reverse walk from top-level page to the
+    # bottom-level card.
+    if haskey(config, "notebook")
+        notebook = config["notebook"]
+        if notebook isa Bool
+            card.notebook = notebook
+        else
+            card.notebook = try
+                parse(Bool, lowercase(notebook))
+            catch err
+                @warn "`notebook` option should be either `\"true\"` or `\"false\"`, instead it is: $notebook. Fallback to unconfigured."
+                nothing
+            end
+        end
+    end
+
     return card
 end
 
@@ -118,6 +138,7 @@ function save_democards(card_dir::String,
                         project_dir=Base.source_dir(),
                         src="src",
                         throw_error = false,
+                        properties = Dict{String, Any}(),
                         kwargs...)
     isdir(card_dir) || mkpath(card_dir)
     cardname = splitext(basename(card.path))[1]
@@ -130,6 +151,20 @@ function save_democards(card_dir::String,
         @warn "The running Julia version `$(VERSION)` is older than the declared compatible version `$(card.julia)`. You might need to upgrade your Julia."
     end
 
+    card.notebook = if isnothing(card.notebook)
+        # Backward compatibility: we used to generate notebooks for all jl files
+        op = get(properties, "notebook", "true")
+        op = isa(op, Bool) ? op : try
+            Base.parse(Bool, lowercase(op))
+        catch err
+            @warn "`notebook` option should be either `\"true\"` or `\"false\"`, instead it is: $op. Fallback to \"true\"."
+            true
+        end
+    else
+        card.notebook
+    end
+    @assert !isnothing(card.notebook)
+
     # 1. generating assets
     cp(card.path, src_path; force=true)
     cd(card_dir) do
@@ -174,14 +209,21 @@ function save_democards(card_dir::String,
     isempty(strip(src_header)) || (src_header *= "\n\n")
 
     # insert header badge
-    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)
+    badges = make_badges(card;
+                         src=src,
+                         card_dir=card_dir,
+                         nbviewer_root_url=nbviewer_root_url,
+                         project_dir=project_dir,
+                         build_notebook=card.notebook) 
+    write(src_path, badges * "\n\n", body)
 
     # 2. notebook
-    try
-        @suppress Literate.notebook(src_path, card_dir; credit=credit)
-    catch err
-        nothing # early warning in the asserts generation
+    if card.notebook
+        try
+            @suppress Literate.notebook(src_path, card_dir; credit=credit)
+        catch err
+            nothing # There are already early warning in the assets generation
+        end
     end
 
     # 3. markdown
@@ -206,19 +248,21 @@ function save_democards(card_dir::String,
     end
 end
 
-function make_badges(card::JuliaDemoCard; src, card_dir, nbviewer_root_url, project_dir)
+function make_badges(card::JuliaDemoCard; src, card_dir, nbviewer_root_url, project_dir, build_notebook)
     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"
+    if build_notebook
+        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)")
     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

src/types/page.jl

@@ -22,6 +22,8 @@ Supported items are:
 * `theme`: specify which card theme should be used to generate the index page. If not specified, it
   will default to `nothing`.
 * `title`: specify the title of this demo page. By default, it's the folder name of `root`. Will be override by `template`.
+* `properties`: a dictionary of properties that can be propagated to its children items. The same properties in
+  the children items, if exist, have higher priority.
 
 The following is an example of `config.json`:
 
@@ -32,7 +34,12 @@ The following is an example of `config.json`:
     "order": [
         "basic",
         "advanced"
-    ]
+    ],
+    "properties": {
+        "notebook": "false",
+        "julia": "1.6",
+        "author": "Johnny Chen"
+    }
 }
 ```
 
@@ -89,6 +96,8 @@ mutable struct DemoPage
     template::String
     theme::Union{Nothing, String}
     title::String
+    # These properties will be shared by all children of it during build time
+    properties::Dict{String, Any}
 end
 
 basename(page::DemoPage) = basename(page.root)
@@ -122,7 +131,7 @@ function DemoPage(root::String)::DemoPage
     config = merge(json_config, config) # template has higher priority over config file
 
     sections = map(DemoSection, section_paths)
-    page = DemoPage(root, sections, "", nothing, "")
+    page = DemoPage(root, sections, "", nothing, "", Dict{String, Any}())
     page.theme = load_config(page, "theme"; config=config)
 
     section_orders = load_config(page, "order"; config=config)
@@ -139,6 +148,10 @@ function DemoPage(root::String)::DemoPage
     template = load_config(page, "template"; config=config)
     page.template = template
 
+    if haskey(config, "properties")
+        properties = config["properties"]::Dict
+        merge!(page.properties, properties)
+    end
     return page
 end