set DemoCards build dir to "docs/src" instead of "docs/src/democards" (#70)

Author: johnnychen94

.gitignore

@@ -5,4 +5,3 @@
 Manifest.toml
 /dev/
 docs/build/
-docs/src/democards

docs/quickstart/index.md

@@ -139,12 +139,9 @@ The pipeline of [`makedemos`](@ref DemoCards.makedemos) is:
 Since all files are generated to `docs/src`, the next step is to leave everything else
 to `Documenter.jl` 💯
 
-!!! tip
-
-    By default, `makedemos` generates all the necessary files to `docs/src/democards`,
-    so it's recommended to put your source files into folders outside `docs/src`,
-    otherwise it will be processed by Documenter _twice_. Also, it's often the case that
-    you need to add `docs/src/democards` to `.gitignore`.
+!!! warning
+    By default, `makedemos` generates all the necessary files to `docs/src`, this means that the
+    data you pass to `makedemos` should not be placed at `docs/src`.
 
 For advanced usage of `DemoCards.jl`, you need to understand the core [concepts](@ref concepts) of it.
 

src/generate.jl

@@ -1,7 +1,6 @@
 """
     makedemos(source::String;
               root = "<current-directory>",
-              destination = "democards",
               src = "src",
               build = "build",
               branch = "gh-pages",
@@ -18,10 +17,10 @@ Processing pipeline:
 4. save/copy cover images
 5. generate postprocess callback function, which includes url-redirection.
 
-!!! note By default, the source demo files are read, processed and save to `docs/src/democards`, so
-    if you put all source demo files in `docs/src`, there will be a duplication of files and assets.
-    Thus, it's recommended to not put your original page folder in `docs/src`, and it's prefered to
-    git ignore `docs/src/democards`
+!!! warning
+    By default, `makedemos` generates all the necessary files to `docs/src/`, this means that the
+    data you pass to `makedemos` should not be placed at `docs/src/`. A recommendation is to
+    put folders in `docs/`. For example, `docs/quickstart` is a good choice.
 
 # Inputs
 
@@ -37,8 +36,8 @@ Processing pipeline:
 
 # Keywords
 
-* `root::String`: should be equal to `Documenter`'s setting. By default it's `"docs"`.
-* `destination::String`: The folder name in generated documentation. By default it's `"democards"`.
+* `root::String`: should be equal to `Documenter`'s setting. Typically it is `"docs"` if this
+  function is called in `docs/make.jl` file.
 * `src::String`: should be equal to `Documenter`'s setting. By default it's `"src"`.
 * `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"`.
@@ -85,13 +84,20 @@ For more details of how `config.json` is configured, please check [`DemoCards.De
 """
 function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
                    root::String = Base.source_dir(),
-                   destination::String = "democards",
                    src::String = "src",
                    build::String = "build",
                    branch::String = "gh-pages",
                    edit_branch::String = "master",
                    credit = true)
 
+    if !(basename(pwd()) == "docs" || basename(root) == "docs" || root == preview_build_dir())
+        # special cases that warnings are not printed:
+        # 1. called from `docs/make.jl`
+        # 2. called from `preview_demos`
+        # 3. pwd() in `docs` -- REPL
+        @warn "Suspicious `root` setting: typically `makedemos` should be called from `docs/make.jl`. " pwd=pwd() root
+    end
+    
     root = abspath(root)
     page_root = abspath(root, source)
 
@@ -102,6 +108,16 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
 
     page = DemoPage(page_root)
 
+    relative_root = basename(page)
+
+    # Where files are generated by DemoCards for Documenter.makedocs
+    # e.g "$PROJECT_ROOT/docs/src/quickstart"
+    absolute_root = abspath(root, src, relative_root)
+
+    if page_root == absolute_root
+        throw(ArgumentError("Demo page $page_root should not be placed at \"docs/$src\" folder."))
+    end
+
     config_file = joinpath(page.root, config_filename)
     if !isnothing(templates)
         Base.depwarn(
@@ -121,13 +137,6 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
         theme_assets = nothing
     end
 
-    relative_root = joinpath(destination, basename(page))
-
-    # Where files are generated by DemoCards for Documenter.makedocs
-    # e.g "$PROJECT_ROOT/docs/src/democards/quickstart"
-    absolute_root = joinpath(root, src, relative_root)
-    isdir(absolute_root) && rm(absolute_root; force=true, recursive=true)
-
     # we can directly pass it to Documenter.makedocs
     if isnothing(templates)
         out_path = walkpage(page; flatten=false) do item
@@ -137,37 +146,75 @@ function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
         out_path = joinpath(relative_root, "index.md")
     end
 
-    @info "SetupDemoCardsDirectory: setting up $(source) directory."
-    rm(absolute_root; force=true, recursive=true)
-    mkpath(absolute_root)
-    # hard coded "covers" should be consistant to card template
-    isnothing(templates) || mkpath(joinpath(absolute_root, "covers"))
-
-    # make a copy before pipeline because `save_democards` modifies card path
-    source_files = [x.path for x in walkpage(page)[2]]
-
-    # pipeline
-    # for themeless version, we don't need to generate covers and index page
-    copy_assets(absolute_root, page)
-    # WARNING: julia cards are reconfigured here
-    save_democards(absolute_root, page;
-                   project_root = root,
-                   src = src,
-                   credit = credit,
-                   nbviewer_root_url = get_nbviewer_root_url(branch))
-    isnothing(templates) || save_cover(joinpath(absolute_root, "covers"), page)
-    isnothing(templates) || generate(joinpath(absolute_root, "index.md"), page, templates)
-
-    # pipeline: generate postprocess callback function
-    postprocess_cb = ()->begin
-        @info "Redirect 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, destination, src, build, edit_branch)
+    @info "SetupDemoCardsDirectory: setting up \"$(source)\" directory."
+    if isdir(absolute_root)
+        # a typical and probably safe case -- that we're still in docs/ folder
+        trigger_prompt = !endswith(dirname(absolute_root), joinpath("docs", "src"))
+
+        if trigger_prompt
+            @warn "DemoCards build dir $absolute_root already exists.\nThis should only happen when you are using DemoCards incorrectly."
+            # Should never reach this in CI environment
+            clean_builddir = input_bool("It might contain important data, do you still want to remove it?")
+        else
+            clean_builddir = true
+        end
+        if clean_builddir
+            @info "Remove DemoCards build dir: $absolute_root"
+            rm(absolute_root; force=true, recursive=true)
+        else
+            error("Stopped demos build.")
         end
     end
 
-    return out_path, postprocess_cb, theme_assets
+    mkpath(absolute_root)
+    try
+        # hard coded "covers" should be consistant to card template
+        isnothing(templates) || mkpath(joinpath(absolute_root, "covers"))
+
+        # make a copy before pipeline because `save_democards` modifies card path
+        source_files = [x.path for x in walkpage(page)[2]]
+
+        # pipeline
+        # for themeless version, we don't need to generate covers and index page
+        copy_assets(absolute_root, page)
+        # WARNING: julia cards are reconfigured here
+        save_democards(absolute_root, page;
+                    project_root = root,
+                    src = src,
+                    credit = credit,
+                    nbviewer_root_url = get_nbviewer_root_url(branch))
+        isnothing(templates) || save_cover(joinpath(absolute_root, "covers"), page)
+        isnothing(templates) || generate(joinpath(absolute_root, "index.md"), page, templates)
+
+        # 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\""
+            rm(absolute_root; force=true, recursive=true)
+
+            if !isnothing(theme_assets)
+                assets_path = abspath(root, src, theme_assets)
+                rm(assets_path, force=true)
+                if(isempty(readdir(dirname(assets_path))))
+                    rm(dirname(assets_path))
+                end
+            end
+        end
+
+        return out_path, postprocess_cb, theme_assets
+
+    catch err
+        # clean up build dir if anything wrong happens here so that we _hopefully_ never trigger the
+        # user prompt logic before the build process.
+        rm(absolute_root; force=true, recursive=true)
+        @error "Errors when building demo dir" pwd=pwd() source root src
+        rethrow(err)
+    end
 end
 
 function generate(file::String, page::DemoPage, args...)
@@ -347,13 +394,13 @@ end
 ### postprocess
 
 """
-    redirect_link(src_file, source, root, destination, src, build, edit_branch)
+    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, destination, src, build, edit_branch)
-    build_file = get_build_file(source_file, source, destination, build)
+function redirect_link(source_file, source, root, src, build, edit_branch)
+    build_file = get_build_file(source_file, source, build)
     if !isfile(build_file)
         @warn "$build_file doesn't exists, skip"
         return nothing
@@ -370,16 +417,16 @@ function redirect_link(source_file, source, root, destination, src, build, edit_
         isnothing(m) && return nothing
         build_url = m.captures[1]
 
-        src_url = get_source_url(build_url, source, basename(source_file), src, destination)
+        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, destination)
+function get_source_url(build_url, source, cardname, src)
     # given input:
     #   - projct_root:          "$REPO/blob/$edit_branch"
-    #   - build_root:           "$projct_root/$docs_root/$src/$destination"
+    #   - build_root:           "$projct_root/$docs_root/$src"
     #   - build_dir:            "$build_root/$prefix/$page/$section/$subsection"
     #   - build_url:            "$build_dir/$cardfile"
     # example of build_url:
@@ -393,28 +440,27 @@ function get_source_url(build_url, source, cardname, src, destination)
     source = replace(source, Base.Filesystem.path_separator => "/")
 
     repo, path = strip.(split(build_url, "/blob/"; limit=2), '/')
-    root_to_subsection = replace(splitdir(path)[1], "$(src)/$(destination)/" => ""; count=1)
+    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, destination, build)
+function get_build_file(source_file, source, build)
     # given inputs:
     #   - source_file: "$source_root/$prefix/$page/$section/$subsection/$card.md"
     #   - source:      "$prefix/$page
-    #   - destination: "democards"
     #   - build:       "build"
     # we need to generate:
-    #   - build_root: "$source_root/$build/$destination"
+    #   - 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 = first(split(source_file, source * sep; limit=2))
-    build_root = joinpath(source_root, build, destination)
+    build_root = joinpath(source_root, build)
     prefix, page = splitdir(source)
 
     source_dir, name = splitdir(source_file)

src/preview.jl

@@ -38,7 +38,6 @@ function preview_demos(demo_path::String;
     # hard code these args in a sandbox environment -- there's no need for customization
     build = "build"
     src = "src"
-    destination = "democards"
 
     demo_path = abspath(rstrip(demo_path, ['/', '\\']))
     ispath(demo_path) || throw(ArgumentError("demo path does not exists: $demo_path"))
@@ -84,14 +83,13 @@ function preview_demos(demo_path::String;
             root = build_dir,
             src = src,
             build = build,
-            destination = destination,
             edit_branch = edit_branch,
             credit = credit
         )
 
         # In cases that addtional Documenter pipeline is not needed
         # This is mostly for test usage right now and might be changed if there is better solution
-        require_html || return abspath(build_dir, src, destination, basename(page_dir))
+        require_html || return abspath(build_dir, src, basename(page_dir))
 
         format = Documenter.HTML(
             edit_link = edit_branch,

src/utils.jl

@@ -341,3 +341,24 @@ end
 
 
 is_remote_url(path) = !isnothing(match(r"^https?://", path))
+
+
+"""
+    input_bool(prompt)::Bool
+
+Print `prompt` message and trigger user input for confirmation.
+"""
+function input_bool(prompt)
+    while true
+        println(prompt, " [y/n]")
+        response = readline()
+        length(response) == 0 && continue
+        reply = lowercase(first(strip(response)))
+        if reply == 'y'
+            return true
+        elseif reply =='n'
+            return false
+        end
+        # Otherwise loop and repeat the prompt
+    end
+end

test/generate.jl

@@ -18,7 +18,7 @@
         cp(abs_root, tmp_root, force=true)
         templates, theme = cardtheme(root=root)
         path, post_process_cb = @suppress_err makedemos(tmp_root, templates, root=root)
-        @test @suppress_err path == joinpath("democards", "default", "index.md")
+        @test @suppress_err path == joinpath("default", "index.md")
         @test theme == joinpath("democards", "gridtheme.css")
     end
 

test/preview.jl

@@ -14,7 +14,7 @@
             demo_file = joinpath(joinpath(page_dir, "subsection_2"), demo_file)
             @test_reference joinpath("references", "preview", basename(demo_file)) read(demo_file, String) by=ignore_CR
         end
-        @test "gridtheme.css" in readdir(dirname(page_dir))
+        @test "gridtheme.css" in readdir(joinpath(dirname(page_dir), "democards"))
     end
 
     @testset "section with non page structure" begin

test/utils.jl

@@ -80,14 +80,14 @@ end
 
 @testset "url_redirect" begin
     source = "quickstart"
-    build_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/src/democards/quickstart/usage_example/julia_demos/2.cover_on_the_fly.md"
+    build_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/src/quickstart/usage_example/julia_demos/2.cover_on_the_fly.md"
     src_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/quickstart/usage_example/julia_demos/2.cover_on_the_fly.jl"
-    @test src_url == DemoCards.get_source_url(build_url, source, "2.cover_on_the_fly.jl", "src", "democards")
+    @test src_url == DemoCards.get_source_url(build_url, source, "2.cover_on_the_fly.jl", "src")
 
-    source = Sys.iswindows() ? raw"theme_gallery\grid" : "theme_gallery/grid"
-    build_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/src/democards/grid/grid_section_1/grid_subsection_1/grid_card_1.md"
+    source = joinpath("theme_gallery", "grid")
+    build_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/src/grid/grid_section_1/grid_subsection_1/grid_card_1.md"
     src_url = "https://github.com/johnnychen94/DemoCards.jl/blob/master/docs/theme_gallery/grid/grid_section_1/grid_subsection_1/grid_card_1.md"
-    @test src_url == DemoCards.get_source_url(build_url, source, "grid_card_1.md", "src", "democards")
+    @test src_url == DemoCards.get_source_url(build_url, source, "grid_card_1.md", "src")
 end
 
 @testset "walkpage" begin