Add Banner for "This is for unreleased docs"

[oxinabox]

as of #1577
Documentor displays a banner for if the docs are for an out-dated page.

A lot of links exist in the wild (especially for older packages) that go to /latest, so search engines often pick up on this.
/latest might be docs for an unreleased version of the packages, or I think even preview builds for open PRs.

It would be nice to display a similar banner on these packages that offers a link to latest stable release.

@aoanla suggested this on JuliaCollections/DataStructures.jl#885 (comment)

[mortenpi]

This seems reasonable. We actually have that for the Julia docs (https://docs.julialang.org/en/v1.11-dev/), although I am not immediately sure if that's accidental due to the slightly different URL scheme, or we inject it somehow.

[sid-008]

Hey there @mortenpi! How can I help with this issue?

[sid-008]

Regarding this issue, it seems like there's a GET request to https://docs.julialang.org/en/v1.11-dev/assets/warner.js that renders the banner, perhaps we could do the same for other packages and offer a link to the latest stable release?

[mortenpi]

As a breadcrumb, the code that handles the outdated warning lives here: https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/html/warner.js

[sid-008]

So, would anything need to be added or changed really? People could just essentially use this script to add the outdated/experimental warning banner right? But I assume this is very much specific to the documentation site?

[mortenpi]

The logic in warner.js needs to be adjusted. It ignores (i.e. never adds the banner for) docs directories that are not version numbers:

Documenter.jl/assets/html/warner.js

Lines 13 to 16 in 8395fe5

	// Current version is not a version number, so we can't tell if it's the newest version. Abort.
	if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) {
	return;
	}

We could make that regex just more permissive somehow, but IIRC we allow both dev/ and stable/ to be configured in deploydocs, so simple string matching is probably not enough. So it's not immediately clear to me what the correct solution here is.

[sid-008]

Rather than the regex testing for it being a version number we could change it to only add the banner to versions ending with dev ? That seems like a workaround of sorts. Would this kind of behaviour be desirable?

Do you have any idea how the juliadocs site tags versions as outdated? Like in https://docs.julialang.org/en/v1.4/ I can't seem to figure it out

[mortenpi]

Do you have any idea how the juliadocs site tags versions as outdated? Like in https://docs.julialang.org/en/v1.4/ I can't seem to figure it out

That's the regex.

Rather than the regex testing for it being a version number we could change it to only add the banner to versions ending with dev ?

The dev string is user-configurable though. We'd need something that would also work even if the dev version is not called dev.

One option would be to add some JS variable to communicate this. In deploydocs

Documenter.jl/src/deploydocs.jl

Lines 412 to 418 in 346c622

	if versions === nothing
	# If the documentation is unversioned and deployed to root, we generate a
	# siteinfo.js file that would disable the version selector in the docs
	HTMLWriter.generate_siteinfo_file(deploy_dir, nothing)
	else
	# Generate siteinfo-file with DOCUMENTER_CURRENT_VERSION
	HTMLWriter.generate_siteinfo_file(deploy_dir, subfolder)

we generate the siteinfo.js file, which contains some of the metadata the JS can use to decide things:

Documenter.jl/src/html/HTMLWriter.jl

Lines 1598 to 1606 in 346c622

	function generate_siteinfo_file(dir::AbstractString, version::Union{AbstractString,Nothing})
	open(joinpath(dir, "siteinfo.js"), "w") do buf
	if version !== nothing
	println(buf, "var DOCUMENTER_CURRENT_VERSION = \"$(version)\";")
	else
	println(buf, "var DOCUMENTER_VERSION_SELECTOR_DISABLED = true;")
	end
	end
	end

[sid-008]

I see, the siteinfo.js file is used to create metadata for the JS to be able to decide things, namely in this case setting:
var DOCUMENTER_CURRENT_VERSION = "v1.4.2"; for example.

The dev string is user-configurable though. We'd need something that would also work even if the dev version is not called dev.
One option would be to add some JS variable to communicate this. In deploydocs

I'll look into ways to fix this, it certainly makes sense to add some JS variables that act as flags to enable/disable it