support computed external links?

[ThomasBreuer]

As far as I understand, Documenter.jl supports internal links via @ref, and external links via the [text](URL) syntax, where URL must be an explicit address.
I am trying to use Documenter.jl for a module that cross-references various entries in the documentation of some other computer system.
The URLs in question may be subject to changes, for example depending on the version number of that system; hard-coded URLs are therefore not a good solution.
At the time when the documentation of the module gets built, these URLs can be computed by a Julia function that belongs to the module.
Would it be possible to extend Documenter.jl such that this kind of computed external links gets supported, or do you have a better idea for this functionality?

Currently I am using the following hack.
Write [text](url-encode) in the documentation, let Documenter.jl process it, and add a post-processing step that replaces each url-encode by the computed URL.
This works in the final HTML version of the documentation, and looks acceptable in the interactive Julia help. However, Documenter.jl issues warnings about invalid local link.

[fredrikekre]

Currently I am using the following hack.
Write text in the documentation, let Documenter.jl process it, and add a post-processing step that replaces each url-encode by the computed URL.
This works in the final HTML version of the documentation, and looks acceptable in the interactive Julia help. However, Documenter.jl issues warnings about invalid local link.

If you just replace it in a preprocess step instead it should not complain.

[ThomasBreuer]

Thanks for your reply.
The point is that the links occur in docstrings inside the Julia code files. Programmatically rewriting the code files whenever the documentation gets processed sounds risky.

[c42f]

It would be great if Documenter allowed the user to customize the logic for @ref lookup.

For JuliaHub we now build and serve most package documentation, and allowing @ref to link documentation between packages would provide a very cohesive user experience.

XRef: #319

[mortenpi]

Some sort of a hook into link generation is definitely something we could do, but I feel that this would need to be hashed out a bit more before it's actionable. Another question is whether we want to overload at-ref -- perhaps a dedicated at-link would make more sense?

However, for the OPs use case, a plugin might be the way to go. You can basically add another build stage that would expand a custom at-ref for you. You can take a look at the implementation of @cite and the discussion in #1162 (comment) (the hook into Documenter is here).

[goerz]

DocumenterInterLinks.jl should provide a solution to this, although it's still experimental.