|
| 1 | +# This is vendored version of code that should eventually moved into DocumenterTools.jl |
| 2 | +# once the generic interface has crystallized, and then DocumenterTools should be added |
| 3 | +# as a dependency here. |
| 4 | +# |
| 5 | +# WIP upstream PR: https://github.com/JuliaDocs/DocumenterTools.jl/pull/78 |
| 6 | +# |
| 7 | +# Note: these functions are not part of MultiDocumenter public API. |
| 8 | + |
| 9 | +""" |
| 10 | + DocumenterTools.update_canonical_links_for_build( |
| 11 | + docs_directory::AbstractString; |
| 12 | + canonical::AbstractString, |
| 13 | + ) |
| 14 | +
|
| 15 | +- **`canonical`**: corresponds to the `canonical` attribute of `Documenter.HTML`, |
| 16 | + specifying the root of the canonical URL. |
| 17 | +""" |
| 18 | +function update_canonical_links_for_version( |
| 19 | + docs_directory::AbstractString; |
| 20 | + canonical::AbstractString |
| 21 | + ) |
| 22 | + canonical = rstrip(canonical, '/') |
| 23 | + |
| 24 | + walkdocs(docs_directory, isdochtml) do fileinfo |
| 25 | + @debug "update_canonical_links: checking $(fileinfo.relpath)" |
| 26 | + # Determine the |
| 27 | + filepath = splitpath(fileinfo.relpath) |
| 28 | + new_canonical_href = if filepath[end] == "index.html" |
| 29 | + joinurl(canonical, filepath[1:end-1]...) * '/' |
| 30 | + else |
| 31 | + joinurl(canonical, filepath[1:end]...) |
| 32 | + end |
| 33 | + |
| 34 | + html = Gumbo.parsehtml(read(fileinfo.fullpath, String)) |
| 35 | + n_canonical_tags::Int = 0 |
| 36 | + dom_updated::Bool = false |
| 37 | + for e in AbstractTrees.PreOrderDFS(html.root) |
| 38 | + is_canonical_element(e) || continue |
| 39 | + n_canonical_tags += 1 |
| 40 | + canonical_href = Gumbo.getattr(e, "href", nothing) |
| 41 | + if canonical_href != new_canonical_href |
| 42 | + Gumbo.setattr!(e, "href", new_canonical_href) |
| 43 | + @warn "canonical_href updated" canonical_href new_canonical_href fileinfo.relpath |
| 44 | + dom_updated = true |
| 45 | + end |
| 46 | + end |
| 47 | + if n_canonical_tags == 0 |
| 48 | + for e in AbstractTrees.PreOrderDFS(html.root) |
| 49 | + e isa Gumbo.HTMLElement || continue |
| 50 | + Gumbo.tag(e) == :head || continue |
| 51 | + canonical_href_element = Gumbo.HTMLElement{:link}( |
| 52 | + [], e, Dict( |
| 53 | + "rel" => "canonical", |
| 54 | + "href" => new_canonical_href, |
| 55 | + ) |
| 56 | + ) |
| 57 | + push!(e.children, canonical_href_element) |
| 58 | + @warn "Added new canonical_href" new_canonical_href fileinfo.relpath |
| 59 | + dom_updated = true |
| 60 | + break |
| 61 | + end |
| 62 | + end |
| 63 | + if dom_updated |
| 64 | + open(io -> print(io, html), fileinfo.fullpath, "w") |
| 65 | + end |
| 66 | + if n_canonical_tags > 1 |
| 67 | + @error "Multiple canonical tags!" file = fileinfo.relpath |
| 68 | + end |
| 69 | + end |
| 70 | +end |
| 71 | + |
| 72 | +is_canonical_element(e) = (e isa Gumbo.HTMLElement) && (Gumbo.tag(e) == :link) && (Gumbo.getattr(e, "rel", nothing) == "canonical") |
| 73 | +joinurl(ps::AbstractString...) = join(ps, '/') |
| 74 | + |
| 75 | +function update_canonical_links( |
| 76 | + docs_directory::AbstractString; |
| 77 | + canonical::AbstractString |
| 78 | + ) |
| 79 | + canonical = rstrip(canonical, '/') |
| 80 | + docs_directory = abspath(docs_directory) |
| 81 | + isdir(docs_directory) || throw(ArgumentError("No such directory: $(docs_directory)")) |
| 82 | + |
| 83 | + redirect_index_html_path = joinpath(docs_directory, "index.html") |
| 84 | + canonical_path = if isfile(redirect_index_html_path) |
| 85 | + redirect_url = get_meta_redirect_url(redirect_index_html_path) |
| 86 | + splitpath(normpath(redirect_url)) |
| 87 | + else |
| 88 | + # Try to extract the list of versions from versions.js |
| 89 | + versions_js = joinpath(docs_directory, "versions.js") |
| 90 | + isfile(versions_js) || throw(ArgumentError("versions.js is missing in $(docs_directory)")) |
| 91 | + versions = map(extract_versions_list(versions_js)) do version_str |
| 92 | + isversion, version_number = if occursin(Base.VERSION_REGEX, version_str) |
| 93 | + true, VersionNumber(version_str) |
| 94 | + else |
| 95 | + false, nothing |
| 96 | + end |
| 97 | + fullpath = joinpath(docs_directory, version_str) |
| 98 | + return (; |
| 99 | + path = version_str, |
| 100 | + path_exists = isdir(fullpath) || islink(fullpath), |
| 101 | + symlink = islink(fullpath), |
| 102 | + isversion, |
| 103 | + version_number, |
| 104 | + fullpath, |
| 105 | + ) |
| 106 | + end |
| 107 | + # We'll filter out a couple of potential bad cases and issue warnings |
| 108 | + filter(versions) do vi |
| 109 | + if !vi.path_exists |
| 110 | + @warn "update_canonical_links: path does not exists or is not a directory" docs_directory vi |
| 111 | + return false |
| 112 | + end |
| 113 | + return true |
| 114 | + end |
| 115 | + # We need to determine the canonical path. This would usually be something like the stable/ |
| 116 | + # directory, but it can have a different name, including being a version number. So first we |
| 117 | + # try to find a non-version directory _that is a symlink_ (so that it wouldn't get confused) |
| 118 | + # previews/ or dev builds. If that fails, we try to find the directory matching `v[0-9]+`, |
| 119 | + # with the highest version number. This does not cover all possible cases, but should be good |
| 120 | + # enough for now. |
| 121 | + if isempty(versions) |
| 122 | + error("Unable to determine the canonical path. Found no version directories") |
| 123 | + end |
| 124 | + |
| 125 | + non_version_symlinks = filter(vi -> !vi.isversion && vi.symlink, versions) |
| 126 | + canonical_version = if isempty(non_version_symlinks) |
| 127 | + # We didn't find any non-version symlinks, so we'll try to find the vN directory now |
| 128 | + # as a fallback. |
| 129 | + version_symlinks = map(versions) do vi |
| 130 | + if !(vi.symlink && vi.isversion) |
| 131 | + return nothing |
| 132 | + end |
| 133 | + m = match(r"^([0-9]+)$", vi.path) |
| 134 | + isnothing(m) && return nothing |
| 135 | + parse(Int, m[1]) => vi |
| 136 | + end |
| 137 | + filter!(!isnothing, version_symlinks) |
| 138 | + if isempty(version_symlinks) |
| 139 | + error("Unable to determine the canonical path. Found no version directories") |
| 140 | + end |
| 141 | + _, idx = findmax(first, version_symlinks) |
| 142 | + version_symlinks[idx][2] |
| 143 | + elseif length(non_version_symlinks) > 1 |
| 144 | + error("Unable to determine the canonical path. Found multiple non-version symlinks.\n$(non_version_symlinks)") |
| 145 | + else |
| 146 | + only(non_version_symlinks) |
| 147 | + end |
| 148 | + (canonical_version.path,) |
| 149 | + end |
| 150 | + canonical_full_root = joinurl(canonical, canonical_path...) |
| 151 | + # If we have determined which version should be the canonical version, we can actually |
| 152 | + # go and run update_canonical_links_for_version on each directory. |
| 153 | + for filename in readdir(docs_directory) |
| 154 | + path = joinpath(docs_directory, filename) |
| 155 | + # We'll skip all files. This includes files such as index.html, which in this |
| 156 | + # directory will likely be the redirect. Also, links should be pointing to other |
| 157 | + # versions, so we'll skip them too. |
| 158 | + if islink(path) || !isdir(path) |
| 159 | + continue |
| 160 | + end |
| 161 | + # For true directories, we check that siteinfo.js file is present, which is a pretty |
| 162 | + # good indicator that it's a proper Documenter build. |
| 163 | + if !isfile(joinpath(path, "siteinfo.js")) |
| 164 | + # We want to warn if we run across any directories that are not Documenter builds. |
| 165 | + # But previews/ is one valid case which may be present and so we shouldn't warn |
| 166 | + # for this one. |
| 167 | + if filename != "previews" |
| 168 | + @warn "update_canonical_links: skipping directory that does not look like a Documenter build" filename docs_directory |
| 169 | + end |
| 170 | + continue |
| 171 | + end |
| 172 | + # Finally, we can run update_canonical_links_for_version on the directory. |
| 173 | + @info "Updating canonical URLs for" docs_directory filename canonical_full_root |
| 174 | + update_canonical_links_for_version(path; canonical = canonical_full_root) |
| 175 | + end |
| 176 | +end |
| 177 | + |
| 178 | +function extract_versions_list(versions_js::AbstractString) |
| 179 | + versions_js = abspath(versions_js) |
| 180 | + isfile(versions_js) || throw(ArgumentError("No such file: $(versions_js)")) |
| 181 | + versions_js_content = read(versions_js, String) |
| 182 | + m = match(r"var\s+DOC_VERSIONS\s*=\s*\[([0-9A-Za-z\"\s.,+-]+)\]", versions_js_content) |
| 183 | + if isnothing(m) |
| 184 | + throw(ArgumentError(""" |
| 185 | + Could not find DOC_VERSIONS in $(versions_js): |
| 186 | + $(versions_js_content)""")) |
| 187 | + end |
| 188 | + versions = strip.(c -> isspace(c) || (c == '"'), split(m[1], ",")) |
| 189 | + filter!(!isempty, versions) |
| 190 | + if isempty(versions) |
| 191 | + throw(ArgumentError(""" |
| 192 | + DOC_VERSIONS empty in $(versions_js): |
| 193 | + $(versions_js_content)""")) |
| 194 | + end |
| 195 | + return versions |
| 196 | +end |
| 197 | + |
| 198 | +function get_meta_redirect_url(indexhtml_path::AbstractString) |
| 199 | + html = Gumbo.parsehtml(read(indexhtml_path, String)) |
| 200 | + for e in AbstractTrees.PreOrderDFS(html.root) |
| 201 | + e isa Gumbo.HTMLElement || continue |
| 202 | + Gumbo.tag(e) == :meta || continue |
| 203 | + Gumbo.getattr(e, "http-equiv", nothing) == "refresh" || continue |
| 204 | + content = Gumbo.getattr(e, "content", nothing) |
| 205 | + if isnothing(content) |
| 206 | + @warn "<meta http-equiv=\"refresh\" ...> with no content attribute" path = indexhtml_path |
| 207 | + continue |
| 208 | + end |
| 209 | + m = match(r"[0-9]+;\s*url=(.*)", content) |
| 210 | + if isnothing(m) |
| 211 | + @warn "Unable to parse content value of <meta http-equiv=\"refresh\" ...>" content path = indexhtml_path |
| 212 | + continue |
| 213 | + end |
| 214 | + return m.captures[1] |
| 215 | + end |
| 216 | + return nothing |
| 217 | +end |
0 commit comments