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

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/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,10 +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` obtained from the closest
-`Project.toml`, `JuliaProject.toml`, or `VERSION` file that defines a `version`,
-respectively from the deployment tag in [`Documenter.deploydocs`](@ref).
-
+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.
@@ -419,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
@@ -480,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,
@@ -508,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),
@@ -563,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

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 = _find_project_version()
+    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,32 +75,29 @@ function write_inventory(doc, ctx)
 end
 
 
-function _find_project_version()
-    current_dir = pwd()
-    parent_dir = dirname(current_dir)
-    while parent_dir != current_dir
-        for filename in ["Project.toml", "JuliaProject.toml"]
-            project_toml = joinpath(current_dir, filename)
-            if isfile(project_toml)
-                project_data = TOML.parsefile(project_toml)
-                if haskey(project_data, "version")
-                    version = project_data["version"]
-                    @debug "Obtained `version=$(repr(version))` for inventory from $(project_toml)"
-                    return version
-                end
-            end
-        end
-        version_file = joinpath(current_dir, "VERSION")
-        if isfile(version_file)
-            version = strip(read(version_file, String))
-            @debug "Obtained `version=$(repr(version))` for inventory from $(version_file)"
-            return version
+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
-        current_dir = parent_dir
-        parent_dir = dirname(current_dir)
+    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
-    @warn "Cannot extract version for inventory from Project.toml"
-    return ""
+    return version
 end
 
 

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

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}

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}

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}

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}

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}

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}

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

@@ -192,8 +192,8 @@ end
                 if isfile(objects_inv)
                     inv = Inventory(objects_inv; root_url="")
                     @test inv.project == "Documenter example"
-                    @test inv.version == string(Documenter.DOCUMENTER_VERSION)
                     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]

test/htmlwriter.jl

@@ -352,32 +352,6 @@ end
         end
     end
 
-    @testset "HTML: _find_project_version (for inventory)" begin
-        mktempdir() do tmpdir
-            write(joinpath(tmpdir, "Project.toml"), raw"""
-            name = "Documenter Test"
-            version = "0.1.0-dev"
-            """)
-            write(joinpath(tmpdir, "JuliaProject.toml"), raw"""
-            name = "Documenter Test"
-            version = "0.2.0-dev"
-            """)
-            write(joinpath(tmpdir, "VERSION"), "\n0.3.0-dev\n")
-            docdir = joinpath(tmpdir, "doc")
-            mkdir(docdir)
-            cd(docdir) do
-                write("VERSION", "0.4.0")
-                @test HTMLWriter._find_project_version() == "0.4.0"
-                rm("VERSION")
-                @test HTMLWriter._find_project_version() == "0.1.0-dev"
-                rm(joinpath("..", "Project.toml"))
-                @test HTMLWriter._find_project_version() == "0.2.0-dev"
-                rm(joinpath("..", "JuliaProject.toml"))
-                @test HTMLWriter._find_project_version() == "0.3.0-dev"
-            end
-        end
-    end
-
 end
 
 end