at-ref to functions in other packages

[tpapp]

From #425 it is my impression that references like

module Foo
"See also [`Bar.fun`](@ref)"
somefun() = 1
end

are unsupported. Is this correct?

However I still think that this is the best way to refer to other packages in docstrings, and I am wondering if at least I could silence the error messages along the lines of

!! Unable to get the binding for '[`Bar.fun`](@ref)'. [src/index.md]

[fredrikekre]

Why would you not want an error message for broken links?

[tpapp]

Ideally, I would want these links to work, ie point to other documentation (happy to specify the package => base url mapping manually), but from #425 it is my impression that this is not going to happen for a while.

So silencing them would be OK, too, so that other relevant errors don't get lost in the noise.

[mortenpi]

happy to specify the package => base url mapping manually

For docstring references it would not be enough though -- you'd still have to build the docs for that package to figure out which manual page the docstring ends up on. But it would be a neat feature, so ideas are welcome -- I think #425 could be reopened.

One option would be that @ref could maybe support external references (exact URLs), a single database of which would then be defined in make.jl.

[fredrikekre]

One option would be that @ref could maybe support external references (exact URLs), a single database of which would then be defined in make.jl.

Something like this already works, or did you have something else in mind?

[`Documenter.makedocs`](https://juliadocs.github.io/Documenter.jl/latest/lib/public/#Documenter.makedocs)

[mortenpi]

I was thinking something like [`Bar.fun`](@ref package-bar), and you'd define "package-bar" in make.jl. This way you could have a single definition of a link (e.g. to the main page of another package), which might be useful if you have to link to the same place many times across the manual. CommonMark has the [link-title][link-ref] links actually which kind of do that, but IIRC the parser in Base does not support that syntax.

But yeah, it does not help with exact references to different docstrings. Full URLs like that is what you can do right now, as you say.

[mortenpi]

As for silencing: not a good idea to just silence all unresolved links, I think, since it would hide typos etc. But could maybe consider having the option to define a list of modules for which, if Documenter sees that a docstring (or maybe even just the corresponding name) exists, we would not throw a message. So, maybe something like docref_ignore = [Bar] in make.jl.

[tpapp]

I think it would be great if Documenter.makedocs could export eg a TOML file when generating the documentation for a package with the

symbol => relative_url_with_anchor

mappings. Then, when another package wanted to refer to docstrings in this package, one would simply specify something like

makedocs(...,
    ref_external_packages = Dict("Foo" => "https://foodocs.github.io/Foo.toml"))

[mortenpi]

Yes, something along those lines could be an option. Static links will get out of date though, but Documenter could to maintain a single HTML page in each doc build that would resolve internal links. E.g. https://foodocs.github.io/redirect/#Bar.fun, which would do a JavaScript redirect to the docstring. This way, if the developer of foo moves manual pages around, the docstring links from your package's docs would still work.