diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fcdd6ce13..d901d15a6e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Theme switcher now includes an "Automatic (OS preference)" option that makes the site follow the user's OS setting. (#1745), (#2085), (#2170) +* Documenter now generates a `.documenter-siteinfo.json` file in the HTML build, that contains some metadata about the build. (#2181) + ### Fixed * Line endings in Markdown source files are now normalized to `LF` before parsing, to work around [a bug in the Julia Markdown parser][julia-29344] where parsing is sensitive to line endings, and can therefore cause platform-dependent behavior. (#1906) diff --git a/src/html/HTMLWriter.jl b/src/html/HTMLWriter.jl index 6bb1c51150..8ad994de6d 100644 --- a/src/html/HTMLWriter.jl +++ b/src/html/HTMLWriter.jl @@ -710,6 +710,8 @@ function render(doc::Documenter.Document, settings::HTML=HTML()) # convert Vector{SearchRecord} to a JSON string + do additional JS escaping println(io, json_jsescape(ctx.search_index), "\n}") end + + generate_siteinfo_json(doc.user.build) end """ @@ -1514,6 +1516,31 @@ function generate_siteinfo_file(dir::AbstractString, version::Union{AbstractStri end end +# The .documenter-siteinfo.json can contain various metadata (such as the Documenter version +# used to generate the docs) that automated tools (like DocumenterTools) can use to when +# performing e.g. post-processing after the fact on the generated docs. +# +# The file should be assumed to contain a JSON object that contains at least a 'documenter' +# field. The 'documenter' field is controlled by Documenter. Other tools are free to modify +# the file and add their own values, preferably in a namespace that is unlikely to cause +# a conflict. +# +# Note: siteinfo.js is generated by `deploydocs` and gets loaded in the HTML, whereas +# .documenter-siteinfo.json gets generated by makedocs and does not normally get loaded +# in the HTML +function generate_siteinfo_json(root::AbstractString) + isdir(root) || error("generate_siteinfo_json: not a directory at $root") + siteinfo = Dict( + "documenter_version" => string(Documenter.DOCUMENTER_VERSION), + "julia_version" => string(VERSION), + "generation_timestamp" => Dates.format(now(), dateformat"yyyy-mm-dd\THH:MM:SS"), + ) + open(joinpath(root, ".documenter-siteinfo.json"), "w") do io + JSON.print(io, Dict("documenter" => siteinfo)) + end + return +end + ## domify(...) # ------------ diff --git a/test/examples/tests.jl b/test/examples/tests.jl index 31e39a6987..b7cb59a4e9 100644 --- a/test/examples/tests.jl +++ b/test/examples/tests.jl @@ -1,4 +1,5 @@ using Test +import JSON # DOCUMENTER_TEST_EXAMPLES can be used to control which builds are performed in # make.jl. But for the tests we need to make sure that all the relevant builds @@ -169,6 +170,18 @@ end @test occursin("expanded_example", issue_491) @test occursin("expanded_setup", issue_491) @test occursin("
expanded_raw
", issue_491) + + # .documenter-siteinfo.json + @testset ".documenter-siteinfo.json" begin + siteinfo_json_file = joinpath(build_dir, ".documenter-siteinfo.json") + @test isfile(siteinfo_json_file) + siteinfo_json = JSON.parse(read(siteinfo_json_file, String)) + @test haskey(siteinfo_json, "documenter") + @test siteinfo_json["documenter"] isa Dict + @test haskey(siteinfo_json["documenter"], "documenter_version") + @test haskey(siteinfo_json["documenter"], "julia_version") + @test haskey(siteinfo_json["documenter"], "generation_timestamp") + end end end