[ANN] DocumenterInterLinks v1.0

I would like to announce the release of the DocumenterInterLinks plugin in it’s first “stable” v1.0.0 release.

As of Documenter v1.3.0, every documentation built with Documenter writes an objects.inv “inventory” file. That inventory contains information about every page, section title, and docstring in the documentation, and the URL at which they can be found. Those items can now be referenced from other project documentations. Since March, many active projects will have had new releases and thus will have automatically gained inventories. This also includes the Julia project itself.

The DocumenterInterLinks plugin is now the second half of the equation. It allows you to define external projects for your documentation and use @extref links to place links to those external projects; see the Usage information. For example (adapted from DocumenterInterLinks’ own docs/make.jl file):

using Documenter
using DocumenterInterLinks

links = InterLinks(
    "Julia" => "https://docs.julialang.org/en/v1/",
    "Documenter" => "https://documenter.juliadocs.org/stable/",
    "DocInventories" => "https://juliadocs.org/DocInventories.jl/stable/",
    "matplotlib" => "https://matplotlib.org/3.7.3/",
)

makedocs(
    # ...
    plugins=[links,],
)

With these mappings, it is now possible to have links like

[`Statistics.mean`](@extref Julia)
[`Documenter.makedocs`](@extref)
[Basic Markdown](@extref Documenter Basic-Markdown)

anywhere in the documentation (including in docstrings). The @extref is similar to Documenter’s built-in @ref syntax, but resolves links via any of the available projects defined in the InterLinks plugin. See the full Syntax description. The documentation of DocumenterInterLinks provides an extensive showcase for its own capabilities.

Since the objects.inv inventory files are compatible with Python’s Intersphinx plugin, it is also possible to link to the documentation of any Python project, like matplotlib above (and vice versa).

24 Likes

This could be super useful for Julia wrappers of Python packages and vice versa.

3 Likes

Already when it was first published, one of my favourite projects, since I am a fan of detailed documentation, and links are an important part of this. Another is of course DocumenterCitations.jl.
Thanks!

4 Likes