Skip to content

Commit

Permalink
Set inventory version (#2449)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
goerz authored Feb 22, 2024
1 parent 45696e1 commit 8e2e5e8
Show file tree
Hide file tree
Showing 16 changed files with 151 additions and 15 deletions.
6 changes: 4 additions & 2 deletions Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand All @@ -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"
Expand All @@ -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"]
1 change: 1 addition & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
50 changes: 50 additions & 0 deletions src/deploydocs.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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")

Check warning on line 304 in src/deploydocs.jl

View check run for this annotation

Codecov / codecov/patch

src/deploydocs.jl#L304

Added line #L304 was not covered by tests
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;
Expand Down
17 changes: 15 additions & 2 deletions src/html/HTMLWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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
Expand Down
33 changes: 31 additions & 2 deletions src/html/write_inventory.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down Expand Up @@ -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))"

Check warning on line 84 in src/html/write_inventory.jl

View check run for this annotation

Codecov / codecov/patch

src/html/write_inventory.jl#L81-L84

Added lines #L81 - L84 were not covered by tests
else
@warn "Cannot extract version for inventory from $(project_toml): no version information"

Check warning on line 86 in src/html/write_inventory.jl

View check run for this annotation

Codecov / codecov/patch

src/html/write_inventory.jl#L86

Added line #L86 was not covered by tests
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)
Expand Down
23 changes: 20 additions & 3 deletions test/deploydocs.jl
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
using Documenter: Documenter, deploydocs, git
using DocInventories: DocInventories, Inventory
using Test
include("TestUtilities.jl"); using Main.TestUtilities

Expand All @@ -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(),
Expand All @@ -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"),
Expand All @@ -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"),
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions test/doctests/doctests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
5 changes: 4 additions & 1 deletion test/doctests/stdouts/1.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
5 changes: 4 additions & 1 deletion test/doctests/stdouts/11.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
5 changes: 4 additions & 1 deletion test/doctests/stdouts/12.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
5 changes: 4 additions & 1 deletion test/doctests/stdouts/3.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
5 changes: 4 additions & 1 deletion test/doctests/stdouts/41.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
5 changes: 4 additions & 1 deletion test/doctests/stdouts/7.stdout
Original file line number Diff line number Diff line change
Expand Up @@ -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}
1 change: 1 addition & 0 deletions test/examples/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions test/examples/tests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
2 changes: 2 additions & 0 deletions test/htmlwriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -351,5 +351,7 @@ end
end
end
end

end

end

0 comments on commit 8e2e5e8

Please sign in to comment.