-
Notifications
You must be signed in to change notification settings - Fork 97
Description
I am seeing this in the Documenter.jl master regression tests against MathOpt.jl (see e.g. this log):
[ Info: CrossReferences: building cross-references.
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/changelog.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/changelog.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.UniversalFallback`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/changelog.md.
│ - Header with slug 'Utilities.UniversalFallback' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/changelog.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/reference/constraints.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/reference/constraints.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/release_notes.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/release_notes.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.UniversalFallback`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/release_notes.md.
│ - Header with slug 'Utilities.UniversalFallback' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/release_notes.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.UniversalFallback`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.UniversalFallback' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.@model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.@model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[`Utilities.Model`](@ref)" in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
│ - Header with slug 'Utilities.Model' is not unique in ../../../.julia/dev/MathOptInterface/docs/src/submodules/Utilities/overview.md.
└ @ Documenter ~/work/Documenter.jl/Documenter.jl/src/utilities/utilities.jl:47
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error [:cross_references] -- terminating build before rendering.
Stacktrace:
The relevant section of the Documenter changelog:
Changed the header crossref step to eagerly fail when encountering a non-unique header slug. (#2668, #2787)
This is potentially breaking and may cause some documentation builds to fail.
Those previously passed but generated incorrect cross-references.
You can fix this by ensuring that you have distinct headers across your markdown pages, or by using the@idsyntax to give the headers unique slugs.
The issue is real: while building your docs may have worked fine, you may have had cross refs pointing to unexpected places.
Indeed, grepping through MathOptInterface.jl for the first reported issue shows this:
$ git grep -n -F '# Utilities.Model'
docs/src/submodules/Utilities/overview.md:14:## Utilities.Model
docs/src/submodules/Utilities/reference.md:9:## Utilities.Model
But which one is the intended / "correct" target of the reference?
CC @mortenpi