/
HTMLWriter.jl
1185 lines (1003 loc) · 42.3 KB
/
HTMLWriter.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
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
"""
A module for rendering `Document` objects to HTML.
# Keywords
[`HTMLWriter`](@ref) uses the following additional keyword arguments that can be passed to
[`Documenter.makedocs`](@ref): `assets`, `sitename`, `analytics`, `authors`, `pages`,
`version`. The behavior of [`HTMLWriter`](@ref) can be further customized by passing
[`Documenter.makedocs`](@ref) a [`HTML`](@ref), which accepts the following keyword
arguments: `prettyurls`, `disable_git`, `edit_branch`, `canonical`.
**`sitename`** is the site's title displayed in the title bar and at the top of the
*navigation menu. This argument is mandatory for [`HTMLWriter`](@ref).
**`pages`** defines the hierarchy of the navigation menu.
**`assets`** can be used to include additional assets (JS, CSS, ICO etc. files). See below
for more information.
# Experimental keywords
**`analytics`** can be used specify the Google Analytics tracking ID.
**`version`** specifies the version string of the current version which will be the
selected option in the version selector. If this is left empty (default) the version
selector will be hidden. The special value `git-commit` sets the value in the output to
`git:{commit}`, where `{commit}` is the first few characters of the current commit hash.
# `HTML` `Plugin` options
The [`HTML`](@ref) [`Documenter.Plugin`](@ref) provides additional customization options
for the [`HTMLWriter`](@ref). For more information, see the [`HTML`](@ref) documentation.
# Page outline
The [`HTMLWriter`](@ref) makes use of the page outline that is determined by the
headings. It is assumed that if the very first block of a page is a level 1 heading,
then it is intended as the page title. This has two consequences:
1. It is then used to automatically determine the page title in the navigation menu
and in the `<title>` tag, unless specified in the `.pages` option.
2. If the first heading is interpreted as being the page title, it is not displayed
in the navigation sidebar.
# Default and custom assets
Documenter copies all files under the source directory (e.g. `/docs/src/`) over
to the compiled site. It also copies a set of default assets from `/assets/html/`
to the site's `assets/` directory, unless the user already had a file with the
same name, in which case the user's files overrides the Documenter's file.
This could, in principle, be used for customizing the site's style and scripting.
The HTML output also links certain custom assets to the generated HTML documents,
specifically a logo and additional javascript files.
The asset files that should be linked must be placed in `assets/`, under the source
directory (e.g `/docs/src/assets`) and must be on the top level (i.e. files in
the subdirectories of `assets/` are not linked).
For the **logo**, Documenter checks for the existence of `assets/logo.png`.
If that's present, it gets displayed in the navigation bar.
Additional JS, ICO, and CSS assets can be included in the generated pages using the
`assets` keyword for `makedocs`. `assets` must be a `Vector{String}` and will include
each listed asset in the `<head>` of every page in the order in which they are listed.
The type of the asset (i.e. whether it is going to be included with a `<script>` or a
`<link>` tag) is determined by the file's extension -- either `.js`, `.ico`, or `.css`.
Adding an ICO asset is primarilly useful for setting a custom `favicon`.
"""
module HTMLWriter
import Markdown
import ...Documenter:
Anchors,
Builder,
Documents,
Expanders,
Formats,
Documenter,
Utilities,
Writers
import ...Utilities.DOM: DOM, Tag, @tags
using ...Utilities.MDFlatten
export HTML
"""
HTML(kwargs...)
Sets the behavior of [`HTMLWriter`](@ref).
# Keyword arguments
**`prettyurls`** (default `true`) -- allows toggling the pretty URLs feature.
By default (i.e. when `prettyurls` is set to `true`), Documenter creates a directory
structure that hides the `.html` suffixes from the URLs (e.g. by default `src/foo.md`
becomes `src/foo/index.html`, but can be accessed with via `src/foo/` in the browser). This
structure is preferred when publishing the generate HTML files as a website (e.g. on GitHub
Pages), which is Documenter's primary use case.
If `prettyurls = false`, then Documenter generates `src/foo.html` instead, suitable for
local documentation builds, as browsers do not normally resolve `foo/` to `foo/index.html`
for local files.
To have pretty URLs disabled in local builds, but still have them enabled for the automatic
CI deployment builds, you can set `prettyurls = get(ENV, "CI", nothing) == "true"` (the
specific environment variable you will need to check may depend on the CI system you are
using, but this will work on Travis CI).
**`disable_git`** can be used to disable calls to `git` when the document is not
in a Git-controlled repository. Without setting this to `true`, Documenter will throw
an error and exit if any of the Git commands fail. The calls to Git are mainly used to
gather information about the current commit hash and file paths, necessary for constructing
the links to the remote repository.
**`edit_branch`** specifies which branch, tag or commit the "Edit on GitHub" links
point to. It defaults to `master`. If it set to `nothing`, the current commit will be used.
**`canonical`** specifies the canonical URL for your documentation. We recommend
you set this to the base url of your stable documentation, e.g. `https://juliadocs.github.io/Documenter.jl/stable`.
This allows search engines to know which version to send their users to. [See
wikipedia for more information](https://en.wikipedia.org/wiki/Canonical_link_element).
Default is `nothing`, in which case no canonical link is set.
"""
struct HTML <: Documenter.Plugin
prettyurls::Bool
disable_git:: Bool
edit_branch:: Union{String, Nothing}
canonical:: Union{String, Nothing}
function HTML(;
prettyurls::Bool = true,
disable_git::Bool = false,
edit_branch::Union{String, Nothing} = "master",
canonical::Union{String, Nothing} = nothing)
new(prettyurls, disable_git, edit_branch, canonical)
end
end
const requirejs_cdn = "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js"
const normalize_css = "https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css"
const google_fonts = "https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"
const fontawesome_css = "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css"
const highlightjs_css = "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"
"""
[`HTMLWriter`](@ref)-specific globals that are passed to [`domify`](@ref) and
other recursive functions.
"""
mutable struct HTMLContext
doc :: Documents.Document
settings :: HTML
logo :: String
scripts :: Vector{String}
documenter_js :: String
search_js :: String
search_index :: IOBuffer
search_index_js :: String
search_navnode :: Documents.NavNode
local_assets :: Vector{String}
end
HTMLContext(doc, settings=HTML()) = HTMLContext(doc, settings, "", [], "", "", IOBuffer(), "", Documents.NavNode("search", "Search", nothing), [])
"""
Returns a page (as a [`Documents.Page`](@ref) object) using the [`HTMLContext`](@ref).
"""
getpage(ctx, path) = ctx.doc.internal.pages[path]
getpage(ctx, navnode::Documents.NavNode) = getpage(ctx, navnode.page)
function render(doc::Documents.Document, settings::HTML=HTML())
!isempty(doc.user.sitename) || error("HTML output requires `sitename`.")
ctx = HTMLContext(doc, settings)
ctx.search_index_js = "search_index.js"
copy_asset("arrow.svg", doc)
let logo = joinpath("assets", "logo.png")
if isfile(joinpath(doc.user.build, logo))
ctx.logo = logo
end
end
ctx.documenter_js = copy_asset("documenter.js", doc)
ctx.search_js = copy_asset("search.js", doc)
push!(ctx.local_assets, copy_asset("documenter.css", doc))
append!(ctx.local_assets, doc.user.assets)
for navnode in doc.internal.navlist
render_page(ctx, navnode)
end
render_search(ctx)
open(joinpath(doc.user.build, ctx.search_index_js), "w") do io
println(io, "var documenterSearchIndex = {\"docs\": [\n")
write(io, String(take!(ctx.search_index)))
println(io, "]}")
end
end
"""
Copies an asset from Documenters `assets/html/` directory to `doc.user.build`.
Returns the path of the copied asset relative to `.build`.
"""
function copy_asset(file, doc)
src = joinpath(Utilities.assetsdir(), "html", file)
alt_src = joinpath(doc.user.source, "assets", file)
dst = joinpath(doc.user.build, "assets", file)
isfile(src) || error("Asset '$file' not found at $(abspath(src))")
# Since user's alternative assets are already copied over in a previous build
# step and they should override documenter's original assets, we only actually
# perform the copy if <source>/assets/<file> does not exist. Note that checking
# the existence of <build>/assets/<file> is not sufficient since the <build>
# directory might be dirty from a previous build.
if isfile(alt_src)
@warn "not copying '$src', provided by the user."
else
ispath(dirname(dst)) || mkpath(dirname(dst))
ispath(dst) && @warn "overwriting '$dst'."
cp(src, dst, force=true)
end
assetpath = normpath(joinpath("assets", file))
# Replace any backslashes in links, if building the docs on Windows
return replace(assetpath, '\\' => '/')
end
# Page
# ------------------------------------------------------------------------------
"""
Constructs and writes the page referred to by the `navnode` to `.build`.
"""
function render_page(ctx, navnode)
@tags html body
page = getpage(ctx, navnode)
head = render_head(ctx, navnode)
navmenu = render_navmenu(ctx, navnode)
article = render_article(ctx, navnode)
htmldoc = DOM.HTMLDocument(
html[:lang=>"en"](
head,
body(navmenu, article)
)
)
open_output(ctx, navnode) do io
print(io, htmldoc)
end
end
function render_head(ctx, navnode)
@tags head meta link script title
src = get_url(ctx, navnode)
page_title = "$(mdflatten(pagetitle(ctx, navnode))) · $(ctx.doc.user.sitename)"
css_links = [
normalize_css,
google_fonts,
fontawesome_css,
highlightjs_css,
]
head(
meta[:charset=>"UTF-8"],
meta[:name => "viewport", :content => "width=device-width, initial-scale=1.0"],
title(page_title),
analytics_script(ctx.doc.user.analytics),
canonical_link_element(ctx.settings.canonical, src),
# Stylesheets.
map(css_links) do each
link[:href => each, :rel => "stylesheet", :type => "text/css"]
end,
script("documenterBaseURL=\"$(relhref(src, "."))\""),
script[
:src => requirejs_cdn,
Symbol("data-main") => relhref(src, ctx.documenter_js)
],
script[:src => relhref(src, "siteinfo.js")],
script[:src => relhref(src, "../versions.js")],
# Custom user-provided assets.
asset_links(src, ctx.local_assets)
)
end
function asset_links(src::AbstractString, assets::Vector)
@tags link script
links = DOM.Node[]
for each in assets
ext = splitext(each)[end]
url = relhref(src, each)
node =
ext == ".ico" ? link[:href => url, :rel => "icon", :type => "image/x-icon"] :
ext == ".css" ? link[:href => url, :rel => "stylesheet", :type => "text/css"] :
ext == ".js" ? script[:src => url] : continue # Skip non-js/css files.
push!(links, node)
end
return links
end
analytics_script(tracking_id::AbstractString) =
isempty(tracking_id) ? Tag(Symbol("#RAW#"))("") : Tag(:script)(
"""
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', '$(tracking_id)', 'auto');
ga('send', 'pageview');
"""
)
function canonical_link_element(canonical_link, src)
@tags link
if canonical_link === nothing
return Tag(Symbol("#RAW#"))("")
else
canonical_link_stripped = rstrip(canonical_link, '/')
href = "$canonical_link_stripped/$src"
return link[:rel => "canonical", :href => href]
end
end
## Search page
# ------------
function render_search(ctx)
@tags article body h1 header hr html li nav p span ul script
src = get_url(ctx, ctx.search_navnode)
head = render_head(ctx, ctx.search_navnode)
navmenu = render_navmenu(ctx, ctx.search_navnode)
article = article(
header(
nav(ul(li("Search"))),
hr(),
render_topbar(ctx, ctx.search_navnode),
),
h1("Search"),
p["#search-info"]("Number of results: ", span["#search-results-number"]("loading...")),
ul["#search-results"]
)
htmldoc = DOM.HTMLDocument(
html[:lang=>"en"](
head,
body(navmenu, article),
script[:src => relhref(src, ctx.search_index_js)],
script[:src => relhref(src, ctx.search_js)],
)
)
open_output(ctx, ctx.search_navnode) do io
print(io, htmldoc)
end
end
# Navigation menu
# ------------------------------------------------------------------------------
function render_navmenu(ctx, navnode)
@tags a form h1 img input nav div select option
src = get_url(ctx, navnode)
navmenu = nav[".toc"]
if !isempty(ctx.logo)
push!(navmenu.nodes,
a[:href => relhref(src, "index.html")](
img[
".logo",
:src => relhref(src, ctx.logo),
:alt => "$(ctx.doc.user.sitename) logo"
]
)
)
end
push!(navmenu.nodes, h1(ctx.doc.user.sitename))
let version_selector = select["#version-selector", :onChange => "window.location.href=this.value"]()
if isempty(ctx.doc.user.version)
push!(version_selector.attributes, :style => "visibility: hidden")
else
push!(version_selector.nodes,
option[
:value => "#",
:selected => "selected",
](ctx.doc.user.version)
)
end
push!(navmenu.nodes, version_selector)
end
push!(navmenu.nodes,
form[".search#search-form", :action => navhref(ctx, ctx.search_navnode, navnode)](
input[
"#search-query",
:name => "q",
:type => "text",
:placeholder => "Search docs",
],
)
)
push!(navmenu.nodes, navitem(ctx, navnode))
navmenu
end
"""
[`navitem`](@ref) returns the lists and list items of the navigation menu.
It gets called recursively to construct the whole tree.
It always returns a [`DOM.Node`](@ref). If there's nothing to display (e.g. the node is set
to be invisible), it returns an empty text node (`DOM.Node("")`).
"""
navitem(ctx, current) = navitem(ctx, current, ctx.doc.internal.navtree)
function navitem(ctx, current, nns::Vector)
nodes = map(nn -> navitem(ctx, current, nn), nns)
filter!(node -> node.name !== DOM.TEXT, nodes)
isempty(nodes) ? DOM.Node("") : DOM.Tag(:ul)(nodes)
end
function navitem(ctx, current, nn::Documents.NavNode)
@tags ul li span a
# We'll do the children first, primarily to determine if this node has any that are
# visible. If it does not and it itself is not visible (including current), then
# we'll hide this one as well, returning an empty string Node.
children = navitem(ctx, current, nn.children)
if nn !== current && !nn.visible && children.name === DOM.TEXT
return DOM.Node("")
end
# construct this item
title = mdconvert(pagetitle(ctx, nn); droplinks=true)
link = if nn.page === nothing
span[".toctext"](title)
else
a[".toctext", :href => navhref(ctx, nn, current)](title)
end
item = (nn === current) ? li[".current"](link) : li(link)
# add the subsections (2nd level headings) from the page
if (nn === current) && current.page !== nothing
subs = collect_subsections(ctx.doc.internal.pages[current.page])
internal_links = map(subs) do s
istoplevel, anchor, text = s
_li = istoplevel ? li[".toplevel"] : li[]
_li(a[".toctext", :href => anchor](mdconvert(text; droplinks=true)))
end
push!(item.nodes, ul[".internal"](internal_links))
end
# add the visible subsections, if any, as a single list
(children.name === DOM.TEXT) || push!(item.nodes, children)
item
end
# Article (page contents)
# ------------------------------------------------------------------------------
function render_article(ctx, navnode)
@tags article header footer nav ul li hr span a
header_links = map(Documents.navpath(navnode)) do nn
title = mdconvert(pagetitle(ctx, nn); droplinks=true)
nn.page === nothing ? li(title) : li(a[:href => navhref(ctx, nn, navnode)](title))
end
topnav = nav(ul(header_links))
# Set the logo and name for the "Edit on.." button.
host_type = Utilities.repo_host_from_url(ctx.doc.user.repo)
if host_type == Utilities.RepoGitlab
host = "GitLab"
logo = "\uf296"
elseif host_type == Utilities.RepoGithub
host = "GitHub"
logo = "\uf09b"
elseif host_type == Utilities.RepoBitbucket
host = "BitBucket"
logo = "\uf171"
else
host = ""
logo = "\uf15c"
end
hoststring = isempty(host) ? " source" : " on $(host)"
if !ctx.settings.disable_git
pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
if Utilities.isabsurl(pageurl)
url = pageurl
else
if !(pageurl == getpage(ctx, navnode).source)
# need to set users path relative the page itself
pageurl = joinpath(first(splitdir(getpage(ctx, navnode).source)), pageurl)
end
url = Utilities.url(ctx.doc.user.repo, pageurl, commit=ctx.settings.edit_branch)
end
if url !== nothing
edit_verb = (ctx.settings.edit_branch === nothing) ? "View" : "Edit"
push!(topnav.nodes, a[".edit-page", :href => url](span[".fa"](logo), " $(edit_verb)$hoststring"))
end
end
art_header = header(topnav, hr(), render_topbar(ctx, navnode))
# build the footer with nav links
art_footer = footer(hr())
if navnode.prev !== nothing
direction = span[".direction"]("Previous")
title = span[".title"](mdconvert(pagetitle(ctx, navnode.prev); droplinks=true))
link = a[".previous", :href => navhref(ctx, navnode.prev, navnode)](direction, title)
push!(art_footer.nodes, link)
end
if navnode.next !== nothing
direction = span[".direction"]("Next")
title = span[".title"](mdconvert(pagetitle(ctx, navnode.next); droplinks=true))
link = a[".next", :href => navhref(ctx, navnode.next, navnode)](direction, title)
push!(art_footer.nodes, link)
end
pagenodes = domify(ctx, navnode)
article["#docs"](art_header, pagenodes, art_footer)
end
function render_topbar(ctx, navnode)
@tags a div span
page_title = string(mdflatten(pagetitle(ctx, navnode)))
return div["#topbar"](span(page_title), a[".fa .fa-bars", :href => "#"])
end
# expand the versions argument from the user
# and return entries and needed symlinks
function expand_versions(dir, versions)
# output: entries and symlinks
entries = String[]
symlinks = Pair{String,String}[]
# read folders and filter out symlinks
available_folders = readdir(dir)
cd(() -> filter!(!islink, available_folders), dir)
# filter and sort release folders
vnum(x) = VersionNumber(x)
version_folders = [x for x in available_folders if occursin(Base.VERSION_REGEX, x)]
sort!(version_folders, lt = (x, y) -> vnum(x) < vnum(y), rev = true)
release_folders = filter(x -> (v = vnum(x); v.prerelease == () && v.build == ()), version_folders)
# pre_release_folders = filter(x -> (v = vnum(x); v.prerelease != () || v.build != ()), version_folders)
major_folders = filter!(x -> (v = vnum(x); v.major != 0),
unique(x -> (v = vnum(x); v.major), release_folders))
minor_folders = filter!(x -> (v = vnum(x); !(v.major == 0 && v.minor == 0)),
unique(x -> (v = vnum(x); (v.major, v.minor)), release_folders))
patch_folders = unique(x -> (v = vnum(x); (v.major, v.minor, v.patch)), release_folders)
filter!(x -> vnum(x) !== 0, major_folders)
# populate output
for entry in versions
if entry == "v#" # one doc per major release
for x in major_folders
vstr = "v$(vnum(x).major).$(vnum(x).minor)"
push!(entries, vstr)
push!(symlinks, vstr => x)
end
elseif entry == "v#.#" # one doc per minor release
for x in minor_folders
vstr = "v$(vnum(x).major).$(vnum(x).minor)"
push!(entries, vstr)
push!(symlinks, vstr => x)
end
elseif entry == "v#.#.#" # one doc per patch release
for x in patch_folders
vstr = "v$(vnum(x).major).$(vnum(x).minor).$(vnum(x).patch)"
push!(entries, vstr)
push!(symlinks, vstr => x)
end
elseif entry == "v^" || (entry isa Pair && entry.second == "v^")
if !isempty(release_folders)
x = first(release_folders)
vstr = isa(entry, Pair) ? entry.first : "v$(vnum(x).major).$(vnum(x).minor)"
push!(entries, vstr)
push!(symlinks, vstr => x)
end
elseif entry isa Pair
k, v = entry
i = findfirst(==(v), available_folders)
if i === nothing
@warn "no match for `versions` entry `$(repr(entry))`"
else
push!(entries, k)
push!(symlinks, k => v)
end
else
@warn "no match for `versions` entry `$(repr(entry))`"
end
end
unique!(entries) # remove any duplicates
# generate remaining symlinks
foreach(x -> push!(symlinks, "v$(vnum(x).major)" => x), major_folders)
foreach(x -> push!(symlinks, "v$(vnum(x).major).$(vnum(x).minor)" => x), minor_folders)
foreach(x -> push!(symlinks, "v$(vnum(x).major).$(vnum(x).minor).$(vnum(x).patch)" => x), patch_folders)
filter!(x -> x.first != x.second, unique!(symlinks))
# assert that none of the links point to another link
for link in symlinks
i = findfirst(x -> link.first == x.second, symlinks)
if i !== nothing
throw(ArgumentError("link `$(link)` incompatible with link `$(symlinks[i])`."))
end
end
return entries, symlinks
end
# write version file
function generate_version_file(versionfile::AbstractString, entries)
open(versionfile, "w") do buf
println(buf, "var DOC_VERSIONS = [")
for folder in entries
println(buf, " \"", folder, "\",")
end
println(buf, "];")
end
end
function generate_siteinfo_file(dir::AbstractString, version::AbstractString)
open(joinpath(dir, "siteinfo.js"), "w") do buf
println(buf, "var DOCUMENTER_CURRENT_VERSION = \"$(version)\";")
end
end
## domify(...)
# ------------
"""
Converts recursively a [`Documents.Page`](@ref), `Markdown` or Documenter
`*Node` objects into HTML DOM.
"""
function domify(ctx, navnode)
page = getpage(ctx, navnode)
sib = SearchIndexBuffer(ctx, navnode)
ret = map(page.elements) do elem
search_append(sib, elem)
domify(ctx, navnode, page.mapping[elem])
end
search_flush(sib)
ret
end
mutable struct SearchIndexBuffer
ctx :: HTMLContext
src :: String
page :: Documents.Page
loc :: String
category :: Symbol
title :: String
page_title :: String
buffer :: IOBuffer
function SearchIndexBuffer(ctx, navnode)
page_title = mdflatten(pagetitle(ctx, navnode))
new(
ctx,
pretty_url(ctx, get_url(ctx, navnode.page)),
getpage(ctx, navnode),
"",
:page,
page_title,
page_title,
IOBuffer()
)
end
end
function search_append(sib, node::Markdown.Header)
search_flush(sib)
sib.category = :section
sib.title = mdflatten(node)
a = sib.page.mapping[node]
sib.loc = "$(a.id)-$(a.nth)"
end
search_append(sib, node) = mdflatten(sib.buffer, node)
function search_flush(sib)
# Replace any backslashes in links, if building the docs on Windows
src = replace(sib.src, '\\' => '/')
ref = "$(src)#$(sib.loc)"
text = String(take!(sib.buffer))
println(sib.ctx.search_index, """
{
"location": "$(jsescape(ref))",
"page": "$(jsescape(sib.page_title))",
"title": "$(jsescape(sib.title))",
"category": "$(jsescape(lowercase(string(sib.category))))",
"text": "$(jsescape(text))"
},
""")
end
"""
Replaces some of the characters in the string with escape sequences so that the strings
would be valid JS string literals, as per the
[ECMAScript® 2017 standard](https://www.ecma-international.org/ecma-262/8.0/index.html#sec-literals-string-literals).
Note that it always escapes both potential `"` and `'` closing quotes.
"""
function jsescape(s)
b = IOBuffer()
# From the ECMAScript® 2017 standard:
#
# > All code points may appear literally in a string literal except for the closing
# > quote code points, U+005C (REVERSE SOLIDUS), U+000D (CARRIAGE RETURN), U+2028 (LINE
# > SEPARATOR), U+2029 (PARAGRAPH SEPARATOR), and U+000A (LINE FEED).
#
# https://www.ecma-international.org/ecma-262/8.0/index.html#sec-literals-string-literals
for c in s
if c === '\u000a' # LINE FEED, i.e. \n
write(b, "\\n")
elseif c === '\u000d' # CARRIAGE RETURN, i.e. \r
write(b, "\\r")
elseif c === '\u005c' # REVERSE SOLIDUS, i.e. \
write(b, "\\\\")
elseif c === '\u0022' # QUOTATION MARK, i.e. "
write(b, "\\\"")
elseif c === '\u0027' # APOSTROPHE, i.e. '
write(b, "\\'")
elseif c === '\u2028' # LINE SEPARATOR
write(b, "\\u2028")
elseif c === '\u2029' # PARAGRAPH SEPARATOR
write(b, "\\u2029")
else
write(b, c)
end
end
String(take!(b))
end
function domify(ctx, navnode, node)
fixlinks!(ctx, navnode, node)
mdconvert(node, Markdown.MD())
end
function domify(ctx, navnode, anchor::Anchors.Anchor)
@tags a
aid = "$(anchor.id)-$(anchor.nth)"
if isa(anchor.object, Markdown.Header)
h = anchor.object
fixlinks!(ctx, navnode, h)
DOM.Tag(Symbol("h$(Utilities.header_level(h))"))(
a[".nav-anchor", :id => aid, :href => "#$aid"](mdconvert(h.text, h))
)
else
a[".nav-anchor", :id => aid, :href => "#$aid"](domify(ctx, navnode, anchor.object))
end
end
struct ListBuilder
es::Vector
end
ListBuilder() = ListBuilder([])
import Base: push!
function push!(lb::ListBuilder, level, node)
@assert level >= 1
if level == 1
push!(lb.es, node)
else
if isempty(lb.es) || typeof(last(lb.es)) !== ListBuilder
push!(lb.es, ListBuilder())
end
push!(last(lb.es), level-1, node)
end
end
function domify(lb::ListBuilder)
@tags ul li
ul(map(e -> isa(e, ListBuilder) ? domify(e) : li(e), lb.es))
end
function domify(ctx, navnode, contents::Documents.ContentsNode)
@tags a
navnode_dir = dirname(navnode.page)
navnode_url = get_url(ctx, navnode)
lb = ListBuilder()
for (count, path, anchor) in contents.elements
path = joinpath(navnode_dir, path) # links in ContentsNodes are relative to current page
path = pretty_url(ctx, relhref(navnode_url, get_url(ctx, path)))
header = anchor.object
url = string(path, '#', anchor.id, '-', anchor.nth)
node = a[:href=>url](mdconvert(header.text; droplinks=true))
level = Utilities.header_level(header)
push!(lb, level, node)
end
domify(lb)
end
function domify(ctx, navnode, index::Documents.IndexNode)
@tags a code li ul
navnode_dir = dirname(navnode.page)
navnode_url = get_url(ctx, navnode)
lis = map(index.elements) do el
object, doc, path, mod, cat = el
path = joinpath(navnode_dir, path) # links in IndexNodes are relative to current page
path = pretty_url(ctx, relhref(navnode_url, get_url(ctx, path)))
url = string(path, "#", Utilities.slugify(object))
li(a[:href=>url](code("$(object.binding)")))
end
ul(lis)
end
function domify(ctx, navnode, docs::Documents.DocsNodes)
[domify(ctx, navnode, node) for node in docs.nodes]
end
function domify(ctx, navnode, node::Documents.DocsNode)
@tags a code div section span
# push to search index
sib = SearchIndexBuffer(ctx, navnode)
sib.loc = node.anchor.id
sib.title = string(node.object.binding)
sib.category = Symbol(Utilities.doccat(node.object))
mdflatten(sib.buffer, node.docstr)
search_flush(sib)
section[".docstring"](
div[".docstring-header"](
a[".docstring-binding", :id=>node.anchor.id, :href=>"#$(node.anchor.id)"](code("$(node.object.binding)")),
" — ", # —
span[".docstring-category"]("$(Utilities.doccat(node.object))"),
"."
),
domify_doc(ctx, navnode, node.docstr)
)
end
function domify_doc(ctx, navnode, md::Markdown.MD)
@tags a
if haskey(md.meta, :results)
# The `:results` field contains a vector of `Docs.DocStr` objects associated with
# each markdown object. The `DocStr` contains data such as file and line info that
# we need for generating correct source links.
map(zip(md.content, md.meta[:results])) do md
markdown, result = md
ret = Any[domify(ctx, navnode, Writers.MarkdownWriter.dropheaders(markdown))]
# When a source link is available then print the link.
if !ctx.settings.disable_git
url = Utilities.url(ctx.doc.internal.remote, ctx.doc.user.repo, result)
if url !== nothing
push!(ret, a[".source-link", :target=>"_blank", :href=>url]("source"))
end
end
ret
end
else
# Docstrings with no `:results` metadata won't contain source locations so we don't
# try to print them out. Just print the basic docstring.
domify(ctx, navnode, Writers.MarkdownWriter.dropheaders(md))
end
end
function domify(ctx, navnode, node::Documents.EvalNode)
node.result === nothing ? DOM.Node[] : domify(ctx, navnode, node.result)
end
# nothing to show for MetaNodes, so we just return an empty list
domify(ctx, navnode, node::Documents.MetaNode) = DOM.Node[]
function domify(ctx, navnode, raw::Documents.RawNode)
raw.name === :html ? Tag(Symbol("#RAW#"))(raw.text) : DOM.Node[]
end
# Utilities
# ------------------------------------------------------------------------------
"""
Opens the output file of the `navnode` in write node. If necessary, the path to the output
file is created before opening the file.
"""
function open_output(f, ctx, navnode)
path = joinpath(ctx.doc.user.build, get_url(ctx, navnode))
isdir(dirname(path)) || mkpath(dirname(path))
open(f, path, "w")
end
"""
Get the relative hyperlink between two [`Documents.NavNode`](@ref)s. Assumes that both
[`Documents.NavNode`](@ref)s have an associated [`Documents.Page`](@ref) (i.e. `.page`
is not `nothing`).
"""
navhref(ctx, to, from) = pretty_url(ctx, relhref(get_url(ctx, from), get_url(ctx, to)))
"""
Calculates a relative HTML link from one path to another.
"""
function relhref(from, to)
pagedir = dirname(from)
# The regex separator replacement is necessary since otherwise building the docs on
# Windows will result in paths that have `//` separators which break asset inclusion.
replace(relpath(to, isempty(pagedir) ? "." : pagedir), r"[/\\]+" => "/")
end
"""
Returns the full path corresponding to a path of a `.md` page file. The the input and output
paths are assumed to be relative to `src/`.
"""
function get_url(ctx, path::AbstractString)
if ctx.settings.prettyurls
d = if basename(path) == "index.md"
dirname(path)
else
first(splitext(path))
end
isempty(d) ? "index.html" : "$d/index.html"
else
Formats.extension(:html, path)
end
end
"""
Returns the full path of a [`Documents.NavNode`](@ref) relative to `src/`.
"""
get_url(ctx, navnode::Documents.NavNode) = get_url(ctx, navnode.page)
"""
If `html_prettyurls` is enabled, returns a "pretty" version of the `path` which can then be
used in links in the resulting HTML file.
"""
function pretty_url(ctx, path::AbstractString)
if ctx.settings.prettyurls
dir, file = splitdir(path)
if file == "index.html"
return length(dir) == 0 ? "" : "$(dir)/"
end
end
return path
end
"""
Tries to guess the page title by looking at the `<h1>` headers and returns the
header contents of the first `<h1>` on a page (or `nothing` if the algorithm
was unable to find any `<h1>` headers).
"""
function pagetitle(page::Documents.Page)
title = nothing
for element in page.elements
if isa(element, Markdown.Header{1})
title = element.text
break
end
end
title
end
function pagetitle(ctx, navnode::Documents.NavNode)
if navnode.title_override !== nothing
# parse title_override as markdown
md = Markdown.parse(navnode.title_override)
# Markdown.parse results in a paragraph so we need to strip that
if !(length(md.content) === 1 && isa(first(md.content), Markdown.Paragraph))
error("Bad Markdown provided for page title: '$(navnode.title_override)'")
end
return first(md.content).content
end
if navnode.page !== nothing
title = pagetitle(getpage(ctx, navnode))
title === nothing || return title
end
"-"
end
"""
Returns an ordered list of tuples, `(toplevel, anchor, text)`, corresponding to level 1 and 2
headings on the `page`. Note that if the first header on the `page` is a level 1 header then
it is not included -- it is assumed to be the page title and so does not need to be included
in the navigation menu twice.
"""
function collect_subsections(page::Documents.Page)
sections = []
title_found = false
for element in page.elements