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.

[mortenpi]

For future reference: Sphinx is able to something like this with the intersphinx extension, so could be a source of inspiration for an implementation.

[aminya]

Any update on this? Can't we have a repository container similar to what @tpapp mentioned? What are the requirements that block this?

To start, we can implement a simple solution. Having something like:

"Foo" => "https://foodocs.github.io/Foo"

and referencing a doc with [bar](@ref Foo), Documenter should search for bar URL that starts with

r"https://foodocs.github.io/Foo/**/bar"

or we can just use the first result from:

https://foodocs.github.io/Foo/dev/search/?q=bar

[timholy]

I'm not such a fan of static links in cases where a better approach might be possible. For those who haven't seen, Pkg devs have taken the really cool step of decoupling packages from git repos; now you can host multiple packages in a single git repository. I will not be surprised if, a year or two from now, many of our biggest ecosystems are using this capability. It would be nice to at least have dynamic links to other packages in the same repo, so that for people who build the docs locally, following links takes you to your local version rather than an outdated hosted copy.

[goerz]

I would strongly support

1. Writing some kind of inventory file to the build folder that maps names to URLs within the documentation
2. Having a plugin that can download that inventory file and use it to resolve unknown references.

For the inventory file, we could just adopt the format used by InterSphinx. I have detailed this in #2366. It offers the added benefit that we would be able to bi-directionally link between any Julia and any Python project (any project using Documenter and any project using Sphinx).

[goerz]

DocumenterInterLinks.jl is now available, although still experimental.

[goerz]

Closed by #2424 and the existence of the DocumenterInterLinks plugin