Adjust test outputs in test/examples to avoid warnings; fix bug in expandfirst handling on Windows

[fingolfin]

... so that we can run those tests with warnonly = false, at least in some specific Julia versions.

Resolves #2798.

[fingolfin]

I am unsure how this was ever correct... I mean, yeah, ideally it would print (:Main,) because that's what is printed in Main. But we are in a sandbox module, and we are replacing the module name in output by Main, so I think this is kinda the best we can hope for?

C.f.:

julia> fullname(@__MODULE__)
(:Main,)

julia> module Foo println(fullname(@__MODULE__)) end
(:Main, :Foo)
Main.Foo

[mortenpi]

We try to fix some of these things up though. I wonder if this regressed at some point..

[fingolfin]

Possibly but I see nothing in the code that would fix this.

Anyway, if this ever worked (and I am not convinced it did, but I am also too lazy to try to reconstruct the exact setup from when this test was added), then it must have been quite some time ago. That's part of the problem this PR was meant to fix: the tests in there did not actually act as tests because except for the gravest kinds of failures (crashes, hard exceptions) any regressions were ignored :-(.

I think the current behavior is OK -- if someone really wants to print the fullname of a module, and this causes a problem, they can file an issue and we can worry about the possibility of a fix then.

[mortenpi]

Yep, agreed.

[fingolfin]

That's just for consistency (I am also tempted to sort these sections by issue number... or maybe each issue test should be in a file of its own?

[fingolfin]

This line is new in Julia 1.11

[fingolfin]

This is necessary to make this test pass in Julia >= 1.12

[fingolfin]

This test caused a bunch of warnings. And it is unclear to me what it even is supposed to test. It was added in 80721fd from PR #485.

My best guess is in commit 80721fd which was part of PR #485 before squashing. It introduces a function fixlinks! which has some Windows specific code:

    if is_windows() && ':' in img.url
        Utilities.warn("Invalid local image: colons not allowed in paths on Windows\n    '$(img.url)' in $(get(navnode.page))")
        return
    end

That function is long gone, but a descendant of the code lives on in local_links!:

    elseif Sys.iswindows() && ':' in path
        @docerror(
            doc, :cross_references,
            "invalid local link/image: colons not allowed in paths on Windows in $(Documenter.locrepr(page.source))",
            link = node
        )
        return
    end

So perhaps this line is about getting coverage for that @docerror

But despite this, I think it is the right move to remove this here: because right now, the test results in "fake coverage": we wouldn't notice if the test for colons was broken because we ignore the output via @quietly and even if we didn't, a failure here would most likely not trigger a CI failure.

So instead, we need a new test which triggers this and then specifically watches out for the result, and checks that it shows a warning/error with the appropriate message. (And that should probably be three tests, one for each instance).

As I mentioned elsewhere, I'd like such a setup also for testing the quality of the locrepr output, i.e. to ensure it shows the "right" file paths.

[fingolfin]

See PR #2822

[fingolfin]

@mortenpi I tried to explain the reasoning behind all changes in PR review comments.

But tests fail on Windows, any help would be appreciated:

===================== @quietly: output from the expression =====================
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: skipped.
[ Info: ExpandTemplates: expanding markdown templates.
┌ Warning: expandorder/AA.md in expandfirst does not exist
└ @ Documenter D:\a\Documenter.jl\Documenter.jl\src\expander_pipeline.jl:45
┌ Error: failed to run `@example` block in examples\src\expandorder\01.md:9-11
│ ```@example
│ isfile("AA.txt") || error("AA.txt missing")
│ ```
│   exception =
│    AA.txt missing
│    Stacktrace:
│      [1] error(s::String)
│        @ Base .\error.jl:44
│      [2] top-level scope
│        @ 01.md:10
│      [3] eval(m::Module, e::Any)
│        @ Core .\boot.jl:489
│      [4] #61
│        @ D:\a\Documenter.jl\Documenter.jl\src\expander_pipeline.jl:856 [inlined]
│      [5] cd(f::Documenter.var"#61#62"{Module, Expr}, dir::String)
│        @ Base.Filesystem .\file.jl:101

[fingolfin]

Ah of course it's right there in the error:

┌ Warning: expandorder/AA.md in expandfirst does not exist
└ @ Documenter D:\a\Documenter.jl\Documenter.jl\src\expander_pipeline.jl:45

My guess would be this is due to a different in path separators, combined with dumb string comparision on the paths. Indeed, the warning is produced here:

function expand(doc::Documenter.Document)
    priority_pages = filter(doc.user.expandfirst) do src
        if src in keys(doc.blueprint.pages)
            return true
        else
            @warn "$(src) in expandfirst does not exist"
            return false
        end
    end

I'll see if using joinpath will help.

But of course other kwargs for mkdocs such as pages use slashes in path just fine. Perhaps those arguments are processed somewhere, and the same processing should be applied to expandfirst ? Perhaps @mortenpi knows.

[fingolfin]

So this uncovered a genuine bug in expandfirst handling on Windows, yay. I've thus added a changelog entry. (And fixed the link in the entry above)