(Perhaps) Incorrectly interpreting square brackets in docstrings as links

[alonsoC1s]

When trying to buld the docs for a package I ran across this error message after running docs/make.jl:

[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
┌ Error: invalid local link/image: file does not exist in src/index.md
│   link =
│    @ast MarkdownAST.Link("idea", "") do
│      MarkdownAST.Text("a, b")
│    end
│    
└ @ Documenter ~/.julia/packages/Documenter/CJeWX/src/utilities/utilities.jl:44
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered an error [:cross_references] -- terminating build before rendering.

I tried googling to no avail, the message had me puzzled.

I created a MWE to understand the error better, here's how to reproduce it: Include something like this on the docstrings of any method (exported or not) of the module being documented:

"""
    foo(x)

Some comment containing, say, an interval of numbers [a, b] (idea)
"""
function foo(x)
    println("foo")
end

Now it's perfectly clear to me that Documenter read the [] () as a Markdown link, even with the space in between.

Initially I turned off linkcheck in Documenter's configuration, but that did not help. The configuration is this:

using mwe
using Documenter

DocMeta.setdocmeta!(mwe, :DocTestSetup, :(using mwe); recursive=true)

makedocs(;
    modules=[mwe],
    authors="Alonso",
    sitename="mwe.jl",
    format=Documenter.HTML(;
        canonical="some.random.url",
        edit_link = "main",
        assets=String[],
    ),
    pages=[
        "Home" => "index.md",
    ],
    checkdocs = :exports,
    linkcheck = false
)

Neither checkdocs nor linkcheck helped avoid the error, even when the offending part of the docstring is not on an exported function, nor a URL.

easy fix: Add any non-space character between [] and ()

The issue: I was wondering if this is expected behaviour. If it is, perhaps it would be nice to mention it on the docs or add a stronger hint of what's happening on the error message.

[mortenpi]

This is from the upstream Markdown standard library parser:

julia> using Markdown

julia> x = md"[a b] ()"
  a b ()

julia> x.content
1-element Vector{Any}:
 Markdown.Paragraph(Any[Markdown.Link(Any["a b"], "")])

Any notes about it should go there: https://docs.julialang.org/en/v1/stdlib/Markdown/#Links

Something to note: this doesn't seem to be consistent with CommonMark, but that doesn't necessarily make it a bug. It is kinda weird, but changing it could be considered breaking.

[odow]

You almost certainly want

"""
    foo(x)

Some comment containing, say, an interval of numbers `[a, b]` (idea)

or

Some comment containing, say, an interval of numbers \$[a, b]\$ (idea)
"""
function foo(x)
    println("foo")
end

[alonsoC1s]

@mortenpi I totally agree, not necessarilly a bug. I thought it might be a good idea to include some information about where the md parsing failed. In the original error I got the text inside the square and round brackets appeared to be part of the parsing source code, and with no clues to a line number in the package the error message was a bit unintuitive