Set inventory version (#2449)

* Obtain inventory version from Project.toml * Overwrite inventory version in `deploydocs` This unconditionally overwrites an existing inventory `version` with the version determined by `deploydocs`. This only happens when `deploydocs` actually knows the version. For `dev`-deployments, an existing `version` is left unchanged. Under normal circumstances, the existing `version` will already be the correct one, so this should do nothing. If the `deploydocs` actually has to *change* the version, that would indicate that something is set up incorrectly, and thus a warning will be printed. * Restrict inventory version from `Project.toml` to standard setups In order to prevent an auto-detected inventory version being incorrect for unusual setups (e.g., monorepo), we only consider a `docs/../Project.toml` file when looking up a version. Everything else will leave the version blank in `makedocs`, respectively require explicitly setting `inventory_version` manually
JuliaDocs · Feb 22, 2024 · 8e2e5e8 · 8e2e5e8
1 parent 45696e1
commit 8e2e5e8
Show file tree

Hide file tree

Showing 16 changed files with 151 additions and 15 deletions.
diff --git a/Project.toml b/Project.toml
@@ -23,6 +23,7 @@ PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 RegistryInstances = "2792f1a3-b283-48e8-9a74-f99dce5104f3"
 SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Unicode = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 
@@ -32,8 +33,8 @@ AbstractTrees = "0.4"
 Base64 = "1.6"
 CodecZlib = "0.7"
 Dates = "1.6"
-DocStringExtensions = "0.4, 0.5, 0.6, 0.7, 0.8, 0.9"
 DocInventories = "0.3.2"
+DocStringExtensions = "0.4, 0.5, 0.6, 0.7, 0.8, 0.9"
 Downloads = "1.4"
 Git = "1"
 IOCapture = "0.2"
@@ -49,15 +50,16 @@ REPL = "1.6"
 Random = "1.6"
 RegistryInstances = "0.1"
 SHA = "0.7, 1.6"
+TOML = "1"
 Test = "1.6"
 UUIDs = "1.6"
 Unicode = "1.6"
 julia = "1.6"
 
 [extras]
+DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
-DocInventories = "43dc2714-ed3b-44b5-b226-857eda1aa7de"
 
 [targets]
 test = ["Random", "UUIDs", "DocInventories"]
diff --git 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
@@ -268,6 +268,17 @@ 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)
+                deploy_version = _get_deploy_version(deploy_subfolder)
+                if !isempty(deploy_version) && (inventory_version != deploy_version)
+                    if !isempty(inventory_version)
+                        @warn "Inventory declares version `$inventory_version`, but `deploydocs` is for version `$deploy_version`. Overwriting inventory version."
+                    end
+                    _patch_inventory_version(objects_inv, deploy_version)
+                end
+            end
             @debug "pushing new documentation to remote: '$deploy_repo:$deploy_branch'."
             mktempdir() do temp
                 git_push(
@@ -282,6 +293,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_deploy_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
@@ -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 by [`deploydocs`](@ref Documenter.deploydocs) for tagged releases.
 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.
@@ -64,6 +66,7 @@ module HTMLWriter
 using Dates: Dates, @dateformat_str, now
 import Markdown
 using MarkdownAST: MarkdownAST, Node
+using TOML
 import JSON
 import Base64
 import SHA
@@ -415,6 +418,13 @@ 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 be a valid version number without a `v` prefix.
+Defaults to the `version` defined in the `Project.toml` file in the parent folder of the
+documentation root. Setting this to an empty string leaves the `version` in the inventory
+unspecified until [`deploydocs`](@ref Documenter.deploydocs) runs and automatically sets the
+`version` for any tagged release.
+
 # Default and custom assets
 
 Documenter copies all files under the source directory (e.g. `/docs/src/`) over
@@ -476,6 +486,7 @@ struct HTML <: Documenter.Writer
     size_threshold_warn :: Int
     size_threshold_ignore :: Vector{String}
     example_size_threshold :: Int
+    inventory_version ::  Union{String,Nothing}
 
     function HTML(;
             prettyurls    :: Bool = true,
@@ -504,6 +515,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 = nothing,
 
             # deprecated keywords
             edit_branch   :: Union{String, Nothing, Default} = Default(nothing),
@@ -559,6 +571,7 @@ struct HTML <: Documenter.Writer
             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,
+            (isnothing(inventory_version) ? nothing : string(inventory_version))
         )
     end
 end

diff --git a/src/html/write_inventory.jl b/src/html/write_inventory.jl
@@ -12,9 +12,12 @@ plugin to link into the documentation from other projects.
 """
 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 isnothing(version)
+        project_toml = joinpath(dirname(doc.user.root), "Project.toml")
+        version = _get_inventory_version(project_toml)
+    end
 
     io_inv_header = open(joinpath(doc.user.build, "objects.inv"), "w")
 
@@ -72,6 +75,32 @@ function write_inventory(doc, ctx)
 end
 
 
+function _get_inventory_version(project_toml)
+    version = ""
+    if isfile(project_toml)
+        project_data = TOML.parsefile(project_toml)
+        if haskey(project_data, "version")
+            version = project_data["version"]
+            @info "Automatic `version=$(repr(version))` for inventory from $(relpath(project_toml))"
+        else
+            @warn "Cannot extract version for inventory from $(project_toml): no version information"
+        end
+    else
+        @warn "Cannot extract version for inventory from $(project_toml): no such file"
+    end
+    if isempty(version)
+        # The automatic `inventory_version` determined in this function is intended only for
+        # projects with a standard layout with Project.toml file in the expected
+        # location (the parent folder of doc.user.root). Any non-standard project should
+        # explicitly set an `inventory_version` as an option to `HTML()` in `makedocs`, or
+        # specifically set `inventory_version=""` so that `_get_inventory_version` is never
+        # called, and thus this warning is suppressed.
+        @warn "Please set `inventory_version` in the `HTML()` options passed to `makedocs`."
+    end
+    return version
+end
+
+
 # URI for :std:label
 function _get_inventory_uri(doc, ctx, name::AbstractString, anchor::Documenter.Anchor)
     filename = relpath(anchor.file, doc.user.build)

diff --git 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
 
@@ -21,6 +22,9 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path
             # Pseudo makedocs products in build/
             mkdir("build")
             write("build/page.html", "...")
+            inventory = Inventory(project="test", version="")
+            objects_inv = joinpath("build", "objects.inv")
+            DocInventories.save(objects_inv, inventory)
             # Create gh-pages and deploy dev/
             @quietly deploydocs(
                 root = pwd(),
@@ -36,13 +40,17 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path
                 devbranch = "master",
             )
             # Deploy 1.1.0 tag
+            # (note that the inventory still declares 1.0.0 as the version, so
+            # this implicitly tests that `deploydocs` overwrites it with the
+            # correct version)
             @quietly deploydocs(
                 root = pwd(),
                 deploy_config = TestDeployConfig(full_repo_path, "1.1.0"),
                 repo = full_repo_path,
                 devbranch = "master",
             )
             # Deploy 2.0.0 tag, but into an archive (so nothing pushed to gh-pages)
+            DocInventories.save(objects_inv, Inventory(project="test", version="2.0.0"))
             @quietly deploydocs(
                 root = pwd(),
                 deploy_config = TestDeployConfig(full_repo_path, "2.0.0"),
@@ -51,6 +59,7 @@ Documenter.authenticated_repo_url(c::TestDeployConfig) = c.repo_path
                 archive = joinpath(pwd(), "ghpages.tar.gz"),
             )
             # Deploy 3.0.0 tag with a tag_prefix---which does not change deployment behavior
+            DocInventories.save(objects_inv, Inventory(project="test", version="3.0.0"))
             @quietly deploydocs(;
                 root = pwd(),
                 deploy_config = TestDeployConfig(full_repo_path, "3.0"),
@@ -78,10 +87,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/doctests/doctests.jl b/test/doctests/doctests.jl
@@ -86,7 +86,9 @@ function onormalize(s)
     # Remove filesystem paths in doctests failures
     s = replace(s, r"(doctest failure in )(.*)$"m => s"\1{PATH}")
     s = replace(s, r"(@ Documenter )(.*)$"m => s"\1{PATH}")
+    s = replace(s, r"(@ Documenter.HTMLWriter )(.*)$"m => s"\1{PATH}")
     s = replace(s, r"(top-level scope at )(.*)$"m => s"\1{PATH}")
+    s = replace(s, r"(Cannot extract version for inventory from )(.*):(.*)$"m => s"\1{PATH}:\3")
     # Remove line numbers from Julia source line references (like in stacktraces)
     # Note: currently only supports top-level files (e.g. ./error.jl, but not ./strings/basic.jl)
     s = replace(s, r"Base \.[\\/]([A-Za-z0-9\.]+):[0-9]+\s*$"m => s"Base ./\1:LL")

diff --git a/test/doctests/stdouts/1.stdout b/test/doctests/stdouts/1.stdout
@@ -6,4 +6,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git a/test/doctests/stdouts/11.stdout b/test/doctests/stdouts/11.stdout
@@ -6,4 +6,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git a/test/doctests/stdouts/12.stdout b/test/doctests/stdouts/12.stdout
@@ -128,4 +128,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git a/test/doctests/stdouts/3.stdout b/test/doctests/stdouts/3.stdout
@@ -6,4 +6,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git a/test/doctests/stdouts/41.stdout b/test/doctests/stdouts/41.stdout
@@ -6,4 +6,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git a/test/doctests/stdouts/7.stdout b/test/doctests/stdouts/7.stdout
@@ -6,4 +6,7 @@
 [ Info: Populate: populating indices.
 [ Info: RenderDocument: rendering document.
 [ Info: HTMLWriter: rendering HTML pages.
-[ Info: Writing inventory file.
+┌ Warning: Cannot extract version for inventory from {PATH}: no such file
+└ @ Documenter.HTMLWriter {PATH}
+┌ Warning: Please set `inventory_version` in the `HTML()` options passed to `makedocs`.
+└ @ Documenter.HTMLWriter {PATH}
diff --git 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
@@ -204,6 +204,7 @@ end
                     inv = Inventory(objects_inv; root_url="")
                     @test inv.project == "Documenter example"
                     if name == "html"
+                        @test inv.version == "$(Documenter.DOCUMENTER_VERSION)+test"
                         @test length(inv("Anonymous function declaration")) == 1
                         if length(inv("Anonymous function declaration")) == 1
                             item = inv("Anonymous function declaration")[1]

diff --git a/test/htmlwriter.jl b/test/htmlwriter.jl
@@ -351,5 +351,7 @@ end
             end
         end
     end
+
 end
+
 end