stop on demo build error (#85)

Previously, demo build error is suppressed as warning. Now that
we have a new keyword `throw_error` that enables you to immediately
stop the build when the demo build fails.

Author: johnnychen94

src/generate.jl

@@ -5,7 +5,8 @@
               build = "build",
               branch = "gh-pages",
               edit_branch = "master",
-              credit = true) -> page_path, postprocess_cb
+              credit = true,
+              throw_error = false) -> page_path, postprocess_cb
 
 Make a demo page for `source` and return the path to the generated index file.
 
@@ -42,7 +43,9 @@ Processing pipeline:
 * `build::String`: should be equal to `Documenter`'s setting. By default it's `"build"`.
 * `edit_branch::String`: should be equal to `Documenter`'s setting. By default it's `"master"`.
 * `branch::String`: should be equal to `Documenter`'s setting. By default it's `"gh-pages"`.
-* `credit::String`: `true` to show a "This page is generated by ..." info. By default it's `true`.
+* `credit::Bool`: `true` to show a "This page is generated by ..." info. By default it's `true`.
+* `throw_error::Bool`: `true` to throw an error when the julia demo build fails; otherwise it will
+  continue the build with warnings.
 
 # Examples
 
@@ -88,7 +91,8 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
                    build::String = "build",
                    branch::String = "gh-pages",
                    edit_branch::String = "master",
-                   credit = true)
+                   credit = true,
+                   throw_error = false)
 
     if !(basename(pwd()) == "docs" || basename(root) == "docs" || root == preview_build_dir())
         # special cases that warnings are not printed:
@@ -182,7 +186,8 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
                     project_root = root,
                     src = src,
                     credit = credit,
-                    nbviewer_root_url = get_nbviewer_root_url(branch))
+                    nbviewer_root_url = get_nbviewer_root_url(branch),
+                    throw_error=throw_error)
         isnothing(templates) || save_cover(joinpath(absolute_root, "covers"), page)
         isnothing(templates) || generate(joinpath(absolute_root, "index.md"), page, templates)
 

src/preview.jl

@@ -22,6 +22,7 @@ Generate a docs preview for a single demo card.
 * `assets = String[]`: this is passed to `Documenter.HTML`
 * `edit_branch = "master"`: same to that in `makedemos`
 * `credit = true`: same to that in `makedemos`
+* `throw_error = false`: same to that in `makedemos`
 * `require_html = true`: if it needs to trigger the Documenter workflow and generate HTML preview.
   If set to `false`, the return value is then the path to the generated `index.md` file. This is an
   experimental keyword and should not be considered stable.
@@ -33,6 +34,7 @@ function preview_demos(demo_path::String;
                       edit_branch = "master",
                       assets = String[],
                       credit = true,
+                      throw_error = false,
                       require_html = true,
                       clean = true)
     # hard code these args in a sandbox environment -- there's no need for customization
@@ -84,7 +86,8 @@ function preview_demos(demo_path::String;
             src = src,
             build = build,
             edit_branch = edit_branch,
-            credit = credit
+            credit = credit,
+            throw_error = throw_error,
         )
 
         # In cases that addtional Documenter pipeline is not needed

src/types/card.jl

@@ -9,6 +9,8 @@ The return type `T` is determined by the extension of the path
 to your demofile. Currently supported types are:
 
 * [`MarkdownDemoCard`](@ref)
+* [`JuliaDemoCard`](@ref)
+
 """
 function democard(path::String)::AbstractDemoCard
     validate_file(path)

src/types/julia.jl

@@ -117,6 +117,7 @@ function save_democards(card_dir::String,
                         nbviewer_root_url,
                         project_dir=Base.source_dir(),
                         src="src",
+                        throw_error = false,
                         kwargs...)
     isdir(card_dir) || mkpath(card_dir)
     cardname = splitext(basename(card.path))[1]
@@ -154,8 +155,17 @@ function save_democards(card_dir::String,
                 isempty(readdir(x)) && rm(x; recursive=true, force=true)
             end
         catch err
-            # throw warnings when generating notebooks
-            err isa LoadError || rethrow(err)
+            if err isa LoadError
+                # TODO: provide more informative debug message
+                @warn "something wrong during the assets generation for demo $cardname.jl"
+                if throw_error
+                    rethrow(err)
+                else
+                    @warn err
+                end
+            else
+                rethrow(err)
+            end
         end
     end
 
@@ -171,7 +181,7 @@ function save_democards(card_dir::String,
     try
         @suppress Literate.notebook(src_path, card_dir; credit=credit)
     catch err
-        @warn err.msg
+        nothing # early warning in the asserts generation
     end
 
     # 3. markdown

test/assets/broken_demo.jl

@@ -0,0 +1 @@
+f(2)

test/generate.jl

@@ -33,4 +33,8 @@
         @test readdir(joinpath(page_dir, "covers")) == ["democards_logo.svg"]
         @test readdir(joinpath(page_dir, "sec")) == ["hidden1.ipynb", "hidden1.jl", "hidden1.md", "hidden2.md", "normal.md"]
     end
+
+    @testset "throw_error" begin
+        @suppress_err @test_throws LoadError preview_demos(joinpath(root, "broken_demo.jl"); throw_error=true)
+    end
 end