Set inventory version in deploydocs

This sets the `version` for the `objects.inv` inventory file as follows:

* If an `inventory_version` is given as an option to `HTML`, use that.
  Otherwise, the inventory `version` is left blank in the `makedocs`
  step
* In `deploydocs`, if the inventory version is blank, patch in a version
  derived from deployment folder name. This will generally set the
  correct version for tagged releases, but result in a blank version for
  `dev`-deployments.

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",

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;

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

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")
 

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,28 +21,37 @@ 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(),
                 deploy_config = TestDeployConfig(full_repo_path, "dev"),
                 repo = full_repo_path,
                 devbranch = "master",
             )
+            DocInventories.save(objects_inv, inventory)  # reset `version`
             # Deploy 1.0.0 tag
             @quietly deploydocs(
                 root = pwd(),
                 deploy_config = TestDeployConfig(full_repo_path, "1.0.0"),
                 repo = full_repo_path,
                 devbranch = "master",
             )
+            DocInventories.save(objects_inv, inventory)  # reset `version`
             # Deploy 1.1.0 tag
             @quietly deploydocs(
                 root = pwd(),
                 deploy_config = TestDeployConfig(full_repo_path, "1.1.0"),
                 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,13 +69,15 @@ 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"))
             @test isfile(joinpath("worktree", "versions.js"))
             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

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,

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]