Skip to content

Documentation breakage with upcoming Documenter.jl release #2877

@fingolfin

Description

@fingolfin

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 @id syntax 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions