-
Notifications
You must be signed in to change notification settings - Fork 14
/
generate.jl
458 lines (387 loc) · 16.9 KB
/
generate.jl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
"""
makedemos(source::String;
root = "<current-directory>",
src = "src",
build = "build",
branch = "gh-pages",
edit_branch = "master",
credit = true,
throw_error = false) -> page_path, postprocess_cb
Make a demo page for `source` and return the path to the generated index file.
Processing pipeline:
1. analyze the folder structure `source` and loading all available configs.
2. copy assets
3. preprocess demo files and save it
4. save/copy cover images
5. generate postprocess callback function, which includes url-redirection.
!!! 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
* `source`: dir path to the root page of your demos; relative to `docs`.
# Outputs
* `page_path`: path to demo page's index. You can directly pass it to `makedocs`.
* `postprocess_cb`: callback function for postprocess. You can call `postprocess_cb()` _after_
`makedocs`.
* `theme_assets`: the stylesheet assets that you may need to pass to `Documenter.HTML`. When the
demo page has no theme, it will return `nothing`.
# Keywords
* `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"`.
* `branch::String`: should be equal to `Documenter`'s setting. By default it's `"gh-pages"`.
* `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.
* `filter_function::Function`: the function is passed each potential `DemoCard`, and the
card is excluded if the function returns false. By default, all potential cards are included.
# Examples
The following is the simplest example for you to start with:
```julia
# 1. preprocess and generate demo files to docs/src
examples, postprocess_cb, demo_assets = makedemos("examples")
assets = []
isnothing(demo_assets) || (push!(assets, demo_assets))
# 2. do the standard Documenter pipeline
makedocs(format = Documenter.HTML(assets = assets),
pages = [
"Home" => "index.md",
examples
])
# 3. postprocess after makedocs
postprocess_cb()
```
By default, it won't generate the index page for your demos. To enable it and configure how index
page is generated, you need to create "examples/config.json", whose contents should looks like the
following:
```json
{
"theme": "grid",
"order": [
"basic",
"advanced"
]
}
```
For more details of how `config.json` is configured, please check [`DemoCards.DemoPage`](@ref).
"""
function makedemos(source::String, templates::Union{Dict, Nothing} = nothing;
root::String = Base.source_dir(),
src::String = "src",
build::String = "build",
branch::String = "gh-pages",
edit_branch::String = "master",
credit = true,
throw_error = false,
filter_function = x -> 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)
if page_root == source
# reach here when source is absolute path
startswith(source, root) || throw(ArgumentError("invalid demo page source $page_root"))
end
page = DemoPage(page_root, filter_function)
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(
"It is not recommended to pass `templates`, please configure the index theme in the config file $(config_file). For example `\"theme\": \"grid\"`",
:makedemos)
end
if !isnothing(page.theme)
page_templates, theme_assets = cardtheme(page.theme; root = root, src = src)
theme_assets = something(page.stylesheet, theme_assets)
if templates != page_templates && templates != nothing
@warn "use configured theme from $(config_file)"
end
templates = page_templates
else
theme_assets = page.stylesheet
end
# we can directly pass it to Documenter.makedocs
if isnothing(templates)
out_path = walkpage(page; flatten=false) do item
splitext(joinpath(relative_root, relpath(item.path, page_root)))[1] * ".md"
end
else
out_path = joinpath(relative_root, "index.md")
end
@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 = isinteractive() && (
!endswith(dirname(absolute_root), joinpath("docs", "src")) &&
!(haskey(ENV, "GITLAB_CI") || haskey(ENV, "GITHUB_ACTIONS"))
)
@info "Deleting folder $absolute_root"
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"
# Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
Base.Sys.iswindows() && GC.gc()
rm(absolute_root; force=true, recursive=true)
else
error("Stopped demos build.")
end
end
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),
throw_error=throw_error)
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 "Clean up DemoCards build dir: \"$source\""
# Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
Base.Sys.iswindows() && GC.gc()
rm(absolute_root; force=true, recursive=true)
if !isnothing(theme_assets)
assets_path = abspath(root, src, theme_assets)
# Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
Base.Sys.iswindows() && GC.gc()
rm(assets_path, force=true)
if isdir(dirname(assets_path))
if(isempty(readdir(dirname(assets_path))))
# Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
Base.Sys.iswindows() && GC.gc()
rm(dirname(assets_path))
end
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.
# Ref: https://discourse.julialang.org/t/find-what-has-locked-held-a-file/23278/2
Base.Sys.iswindows() && GC.gc()
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...)
check_ext(file, :markdown)
open(file, "w") do f
generate(f, page::DemoPage, args...)
end
end
generate(io::IO, page::DemoPage, args...) = write(io, generate(page, args...))
function generate(page::DemoPage, templates)
items = Dict("democards" => generate(page.sections, templates; properties=page.properties))
Mustache.render(page.template, items)
end
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; properties=properties)
end
mapreduce(*, filter(x->!x.hidden, cards); init="") do x
generate(x, template; properties=properties)
end
end
function generate(secs::AbstractVector{DemoSection}, templates; level=1, properties=Dict{String, Any}())
mapreduce(*, secs; init="") do x
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, properties=Dict{String, Any}())
header = if length(sec.title) > 0
repeat("#", level) * " " * sec.title
else
""
end * '\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, properties=properties)
else
items = Dict(
"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; properties=Dict{String, Any})
covername = get_covername(card)
if isnothing(covername)
# `generate` are called after `save_cover`, we assume that this default cover file is
# already generated
coverpath = "covers/" * basename(get_logopath())
else
coverpath = is_remote_url(card.cover) ? covername : "covers/" * covername
end
description = card.description
cut_idx = 500
if length(card.description) >= cut_idx
# cut descriptions into ~500 characters
offset = findfirst(' ', description[cut_idx:end])
offset === nothing && (offset = 0)
offset = cut_idx + offset - 2
description = description[1:cut_idx] * "..."
end
items = Dict(
"coverpath" => coverpath,
"id" => card.id,
"title" => card.title,
"description" => description,
)
Mustache.render(template, items)
end
### save demo card covers
save_cover(path::String, page::DemoPage) = save_cover.(path, page.sections)
function save_cover(path::String, sec::DemoSection)
save_cover.(path, sec.subsections)
save_cover.(path, sec.cards)
end
"""
save_cover(path::String, card::AbstractDemoCard)
process the cover image and save it.
"""
function save_cover(path::String, card::AbstractDemoCard)
covername = get_covername(card)
if isnothing(covername)
default_coverpath = get_logopath()
cover_path = joinpath(path, basename(default_coverpath))
!isfile(cover_path) && cp(default_coverpath, cover_path)
# now card uses default cover file as a fallback
card.cover = basename(default_coverpath)
return nothing
end
is_remote_url(card.cover) && return nothing
# only save cover image if it is a existing local file
src_path = joinpath(dirname(card.path), card.cover)
if !isfile(src_path)
@warn "cover file doesn't exist" cover_path=src_path
# reset it back to nothing and fallback to use default cover
card.cover = nothing
save_cover(path, card)
else
cover_path = joinpath(path, covername)
if isfile(cover_path)
@warn "cover file already exists, perhaps you have demos of the same filename" cover_path
end
!isfile(cover_path) && cp(src_path, cover_path)
end
end
function get_covername(card::AbstractDemoCard)
isnothing(card.cover) && return nothing
is_remote_url(card.cover) && return card.cover
default_covername = basename(get_logopath())
card.cover == default_covername && return default_covername
return splitext(basename(card))[1] * splitext(card.cover)[2]
end
get_logopath() = joinpath(pkgdir(DemoCards), "assets", "democards_logo.svg")
### save markdown files
"""
save_democards(root::String, page::DemoPage; credit, nbviewer_root_url)
recursively process and save source demo file
"""
function save_democards(root::String, page::DemoPage; kwargs...)
@debug page.root
save_democards.(root, page.sections; properties=page.properties, kwargs...)
end
function save_democards(root::String, sec::DemoSection; properties, kwargs...)
@debug sec.root
properties = merge(properties, sec.properties) # sec.properties has higher priority
save_democards.(joinpath(root, basename(sec.root)), sec.subsections;
properties=properties, kwargs...)
save_democards.(joinpath(root, basename(sec.root)), sec.cards;
properties=properties, kwargs...)
end
### copy assets
function copy_assets(path::String, page::DemoPage)
_copy_assets(dirname(path), page.root)
copy_assets.(path, page.sections)
end
function copy_assets(path::String, sec::DemoSection)
_copy_assets(path, sec.root)
copy_assets.(joinpath(path, basename(sec.root)), sec.subsections)
end
function _copy_assets(dest_root::String, src_root::String)
# copy assets of this section
assets_dirs = filter(x->isdir(x)&&(basename(x) in ignored_dirnames),
joinpath.(src_root, readdir(src_root)))
map(assets_dirs) do src
dest = joinpath(dest_root, basename(src_root), basename(src))
mkpath(dest)
cp(src, dest; force=true)
end
end
# modified from https://github.com/fredrikekre/Literate.jl to replace the use of @__NBVIEWER_ROOT_URL__
function get_nbviewer_root_url(branch)
if haskey(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL") # Travis CI
repo_slug = get(ENV, "TRAVIS_REPO_SLUG", "unknown-repository")
deploy_folder = if get(ENV, "TRAVIS_PULL_REQUEST", nothing) == "false"
tag = ENV["TRAVIS_TAG"]
isempty(tag) ? "dev" : tag
else
"previews/PR$(get(ENV, "TRAVIS_PULL_REQUEST", "##"))"
end
return "https://nbviewer.jupyter.org/github/$(repo_slug)/blob/$(branch)/$(deploy_folder)"
elseif haskey(ENV, "GITHUB_ACTIONS")
repo_slug = get(ENV, "GITHUB_REPOSITORY", "unknown-repository")
deploy_folder = if get(ENV, "GITHUB_EVENT_NAME", nothing) == "push"
if (m = match(r"^refs\/tags\/(.*)$", get(ENV, "GITHUB_REF", ""))) !== nothing
String(m.captures[1])
else
"dev"
end
elseif (m = match(r"refs\/pull\/(\d+)\/merge", get(ENV, "GITHUB_REF", ""))) !== nothing
"previews/PR$(m.captures[1])"
else
"dev"
end
return "https://nbviewer.jupyter.org/github/$(repo_slug)/blob/$(branch)/$(deploy_folder)"
elseif haskey(ENV, "GITLAB_CI")
if (url = get(ENV, "CI_PROJECT_URL", nothing)) !== nothing
cfg["repo_root_url"] = "$(url)/blob/$(devbranch)"
end
if (url = get(ENV, "CI_PAGES_URL", nothing)) !== nothing &&
(m = match(r"https://(.+)", url)) !== nothing
return "https://nbviewer.jupyter.org/urls/$(m[1])"
end
end
return ""
end