Add a siteinfo JSON file generated by makedocs (#2181)

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)

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(...)
 # ------------
 

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("<p>expanded_raw</p>", 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