diff --git a/docs/make.jl b/docs/make.jl index 856d62b7dc..1a872643bf 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -32,6 +32,7 @@ makedocs( highlights = ["yaml"], ansicolor = true, size_threshold_ignore = ["release-notes.md"], + inventory_version = Documenter.DOCUMENTER_VERSION, ) end, build = ("pdf" in ARGS) ? "build-pdf" : "build", diff --git a/src/deploydocs.jl b/src/deploydocs.jl index 26f06f9565..117387c32a 100644 --- a/src/deploydocs.jl +++ b/src/deploydocs.jl @@ -268,6 +268,24 @@ function deploydocs(; @debug "running extra build steps." make() end + objects_inv = joinpath(realpath(target), "objects.inv") + if isfile(objects_inv) + inventory_version = _get_inventory_version(objects_inv) + deployment_version = _get_deployment_version(deploy_subfolder) + if isempty(deployment_version) + if isempty(inventory_version) + @error "Cannot determine project version for inventory. Please set `inventory_version` in the `HTML` options in `makedocs`." + end + else + if isempty(inventory_version) + _patch_inventory_version(objects_inv, deployment_version) + else + if inventory_version != deployment_version + error("Inventory declares version $inventory_version, but deploy_docs is for version $deployment_version") + end + end + end + end @debug "pushing new documentation to remote: '$deploy_repo:$deploy_branch'." mktempdir() do temp git_push( @@ -282,6 +300,45 @@ function deploydocs(; end end + +function _get_inventory_version(objects_inv) + open(objects_inv) do input + for line in eachline(input) + if startswith(line, "# Version:") + return strip(line[11:end]) + end + end + error("Invalid $objects_inv: missing or invalid version line") + end +end + + +function _patch_inventory_version(objects_inv, version) + objects_inv_patched = tempname() + open(objects_inv) do input + open(objects_inv_patched, "w") do output + for line in eachline(input; keep=true) + if startswith(line, "# Version:") + @debug "Patched $objects_inv with version=$version" + line = "# Version: $version\n" + end + write(output, line) + end + end + end + mv(objects_inv_patched, objects_inv; force=true) +end + + +function _get_deployment_version(foldername) + try + return string(VersionNumber(foldername)) # strips the leading "v" from foldername + catch + return "" + end +end + + """ git_push( root, tmp, repo; diff --git a/src/html/HTMLWriter.jl b/src/html/HTMLWriter.jl index 5c7eb699f5..d150782643 100644 --- a/src/html/HTMLWriter.jl +++ b/src/html/HTMLWriter.jl @@ -25,7 +25,7 @@ selector will be hidden. The special value `git-commit` sets the value in the ou # `HTML` `Plugin` options -The [`HTML`](@ref) [`Documenter.Plugin`](@ref) provides additional customization options +The [`HTML`](@ref) object provides additional customization options for the [`HTMLWriter`](@ref). For more information, see the [`HTML`](@ref) documentation. # Page outline @@ -54,7 +54,9 @@ to link to any other project with an inventory file, see The [format of the `objects.inv` file](https://juliadocs.org/DocInventories.jl/stable/formats/#Sphinx-Inventory-Format) is borrowed from the [Sphinx project](https://www.sphinx-doc.org/en/master/). It consists of a plain text header that includes the project name, taken from the `sitename` argument -to [`Documenter.makedocs`](@ref), and a project `version` (currently empty). +to [`Documenter.makedocs`](@ref), and a project `version` taken from the +`inventory_version` argument of the [`HTML`](@ref) options, or automatically +determined during [deployment](@ref Documenter.deploydocs). The bulk of the file is a list of plain text records, compressed with gzip. See [Inventory Generation](http://juliadocs.org/DocumenterInterLinks.jl/stable/write_inventory/) for details on these records. @@ -415,6 +417,9 @@ executable to be available in `PATH` or to be passed as the `node` keyword. **`highlightjs`** file path to custom highglight.js library to be used with prerendering. +**`inventory_version`** a version string to write to the header of the +`objects.inv` inventory file. This should not include a `v` prefix. + # Default and custom assets Documenter copies all files under the source directory (e.g. `/docs/src/`) over @@ -476,6 +481,7 @@ struct HTML <: Documenter.Writer size_threshold_warn :: Int size_threshold_ignore :: Vector{String} example_size_threshold :: Int + inventory_version :: String function HTML(; prettyurls :: Bool = true, @@ -504,6 +510,7 @@ struct HTML <: Documenter.Writer # seems reasonable, and that would lead to ~80 KiB, which is still fine # and leaves a buffer before hitting `size_threshold_warn`. example_size_threshold :: Union{Integer, Nothing} = 8 * 2^10, # 8 KiB + inventory_version :: Union{AbstractString,VersionNumber} = "", # deprecated keywords edit_branch :: Union{String, Nothing, Default} = Default(nothing), @@ -558,7 +565,8 @@ struct HTML <: Documenter.Writer new(prettyurls, disable_git, edit_link, repolink, canonical, assets, analytics, collapselevel, sidebar_sitename, highlights, mathengine, description, footer, ansicolor, lang, warn_outdated, prerender, node, highlightjs, - size_threshold, size_threshold_warn, size_threshold_ignore, example_size_threshold, + size_threshold, size_threshold_warn, size_threshold_ignore, + example_size_threshold, string(inventory_version), ) end end diff --git a/src/html/write_inventory.jl b/src/html/write_inventory.jl index 68a93dfd45..c4ee991b7b 100644 --- a/src/html/write_inventory.jl +++ b/src/html/write_inventory.jl @@ -14,7 +14,8 @@ function write_inventory(doc, ctx) @info "Writing inventory file." project = doc.user.sitename - version = "" # TODO: https://github.com/JuliaDocs/Documenter.jl/issues/2385 + version = ctx.settings.inventory_version + # if `version` is empty, it will be patched during `deploydocs` io_inv_header = open(joinpath(doc.user.build, "objects.inv"), "w") diff --git a/test/deploydocs.jl b/test/deploydocs.jl index 27fdac0007..283acfa346 100644 --- a/test/deploydocs.jl +++ b/test/deploydocs.jl @@ -1,4 +1,5 @@ using Documenter: Documenter, deploydocs, git +using DocInventories: DocInventories, Inventory using Test include("TestUtilities.jl"); using Main.TestUtilities @@ -20,7 +21,13 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path full_repo_path = joinpath(pwd(), "repo") # Pseudo makedocs products in build/ mkdir("build") - write("build/page.html", "...") + write(joinpath("build", "page.html"), "...") + inventory = Inventory( + project="Documenter deploydocs test", + version="", + ) + objects_inv = joinpath("build", "objects.inv") + DocInventories.save(objects_inv, inventory) # Create gh-pages and deploy dev/ @quietly deploydocs( root = pwd(), @@ -28,6 +35,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path repo = full_repo_path, devbranch = "master", ) + DocInventories.save(objects_inv, inventory) # reset `version` # Deploy 1.0.0 tag @quietly deploydocs( root = pwd(), @@ -35,6 +43,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path repo = full_repo_path, devbranch = "master", ) + DocInventories.save(objects_inv, inventory) # reset `version` # Deploy 1.1.0 tag @quietly deploydocs( root = pwd(), @@ -42,6 +51,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path repo = full_repo_path, devbranch = "master", ) + DocInventories.save(objects_inv, inventory) # reset `version` # Deploy 2.0.0 tag, but into an archive (so nothing pushed to gh-pages) @quietly deploydocs( root = pwd(), @@ -50,6 +60,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path devbranch = "master", archive = joinpath(pwd(), "ghpages.tar.gz"), ) + DocInventories.save(objects_inv, inventory) # reset `version` # Deploy 3.0.0 tag with a tag_prefix---which does not change deployment behavior @quietly deploydocs(; root = pwd(), @@ -58,6 +69,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path devbranch = "master", tag_prefix = "MySubPackage-", ) + DocInventories.save(objects_inv, inventory) # reset `version` # Check what we have in gh-pages now: run(`$(git()) clone -q -b gh-pages $(full_repo_path) worktree`) @test isfile(joinpath("worktree", "index.html")) @@ -65,6 +77,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path for d in ["dev", "v1.0.0", "v1.1.0", "v3.0.0"] @test isfile(joinpath("worktree", d, "page.html")) @test isfile(joinpath("worktree", d, "siteinfo.js")) + @test isfile(joinpath("worktree", d, "objects.inv")) end @test islink(joinpath("worktree", "v1")) @test islink(joinpath("worktree", "v1.0")) @@ -78,10 +91,18 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path @test islink(joinpath("worktree", "v3")) @test islink(joinpath("worktree", "v3.0")) @test islink(joinpath("worktree", "v3.0.0")) - + inv_v11 = Inventory(joinpath("worktree", "v1.1", "objects.inv")) + @test inv_v11.version == "1.1.0" + inv_v30 = Inventory(joinpath("worktree", "v3.0", "objects.inv")) + @test inv_v30.version == "3.0.0" + inv_stable = Inventory(joinpath("worktree", "stable", "objects.inv")) + @test inv_stable.version == "3.0.0" + inv_dev = Inventory(joinpath("worktree", "dev", "objects.inv")) + @test inv_dev.version == "" + # key_prefix does not affect/is not present in worktree directories - @test issetequal([".git", "1.0.0", "1.1.0", "3.0", "dev", "index.html", - "stable", "v1", "v1.0", "v1.0.0", "v1.1", "v1.1.0", + @test issetequal([".git", "1.0.0", "1.1.0", "3.0", "dev", "index.html", + "stable", "v1", "v1.0", "v1.0.0", "v1.1", "v1.1.0", "v3", "v3.0", "v3.0.0", "versions.js"], readdir("worktree")) end end diff --git a/test/examples/make.jl b/test/examples/make.jl index 3a6912a5c6..c68ac357cb 100644 --- a/test/examples/make.jl +++ b/test/examples/make.jl @@ -283,6 +283,7 @@ function html_doc( mathengine = mathengine, highlights = ["erlang", "erlang-repl"], footer = "This footer has been customized.", + inventory_version = "$(Documenter.DOCUMENTER_VERSION)+test", htmlkwargs... ), warnonly = warnonly, diff --git a/test/examples/tests.jl b/test/examples/tests.jl index 308ddcc7b5..b51c317149 100644 --- a/test/examples/tests.jl +++ b/test/examples/tests.jl @@ -193,6 +193,7 @@ end inv = Inventory(objects_inv; root_url="") @test inv.project == "Documenter example" if name == "html" + @test endswith(inv.version, "+test") @test length(inv("Anonymous function declaration")) == 1 if length(inv("Anonymous function declaration")) == 1 item = inv("Anonymous function declaration")[1]