DocumenterInterLinks.jl

DocumenterInterLinks.jl is a plugin for Documenter.jl to link to external projects. It is interoperable with Intersphinx for Python projects.

Installation Instructions

As usual, the package can be installed via

] add DocumenterInterLinks

in the Julia REPL, or by adding

DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"

to the relevant Project.toml file (e.g., docs/Project.toml).

Usage

In your docs/make.jl file, load the DocumenterInterLinks package (using DocumenterInterLinks).
Declare external projects by instantiating an InterLinks object and passing it as part of plugins to Documenter.makedocs.
Reference items from any external project with an @extref link in your documentation.

Declaring External Projects

In docs/make.jl, instantiate an InterLinks object to define external projects you want to link to. For example,

using DocumenterInterLinks

links = InterLinks(
    "sphinx" => "https://www.sphinx-doc.org/en/master/",
    "matplotlib" => "https://matplotlib.org/3.7.3/objects.inv",
    "Julia" => (
        "https://docs.julialang.org/en/v1/",
        joinpath(@__DIR__, "inventories", "Julia.toml")
    ),
    "Documenter" => (
        "https://documenter.juliadocs.org/stable/",
        "https://documenter.juliadocs.org/stable/objects.inv",
        joinpath(@__DIR__, "inventories", "Documenter.toml")
    ),
);

defines the external projects "sphinx", "matplotlib", and "Julia". For each project, it specifies the root URL of that project's online documentation and the location of an inventory file.

The above examples illustrates three possibilities for specifying the root url and inventory location

Map that project name to project root URL. This will look for an inventory file objects.inv directly underneath the given URL. This is the recommended from in most cases.
Map the project name to the URL of an inventory file. The project root URL is the given URL without the filename.
Map the project name to a tuple containing the root URL first, and then one or more possible locations for an inventory file. These may be local file paths, which allows using a self-maintained inventory file for a project that does not provide one.

See the doc-string of InterLinks for details.

Warning

The instantiated links object must be passed to Documenter.makedocs as an element to the plugins keyword argument.

The inventory files referenced when instantiating InterLinks are assumed to have been created by a documentation generator, see Inventory Generation. The DocInventories package is used as a backend to parse these files into DocInventories.Inventory objects. These are accessible by using links as a dict:

links["sphinx"]

Inventory(
 project="Sphinx",
 version="7.3.0",
 root_url="https://www.sphinx-doc.org/en/master/",
 items=[
  InventoryItem(":js:function:`\$.getJSON`" => "usage/domains/javascript.html#getJSON"),
  InventoryItem(":c:member:`@alias.data`" => "usage/domains/c.html#c.\$", dispname="[anonymous].data"),
  InventoryItem(":c:function:`@alias.f`" => "usage/domains/c.html#c.\$", dispname="[anonymous].f"),
  InventoryItem(":c:functionParam:`@alias.f.k`" => "usage/domains/c.html#c.@alias.f", dispname="[anonymous].f.k"),
  InventoryItem(":cpp:type:`CustomList`" => "tutorial/describing-code.html#_CPPv410\$"),
  ⋮ (1536 elements in total)
  InventoryItem(":std:label:`websupportquickstart`" => "usage/advanced/websupport/quickstart.html#\$", dispname="Web Support Quick Start"),
  InventoryItem(":std:label:`when-deprecation-warnings-are-displayed`" => "man/sphinx-build.html#\$", dispname="Deprecation Warnings"),
  InventoryItem(":std:label:`windows-other-method`" => "usage/installation.html#\$", dispname="Other Methods"),
  InventoryItem(":std:label:`writing-builders`" => "extdev/builderapi.html#\$", dispname="Builder API"),
  InventoryItem(":std:confval:`xml_pretty`" => "usage/configuration.html#confval-\$", priority=1),
  InventoryItem(":std:label:`xref-syntax`" => "usage/referencing.html#\$", dispname="Cross-referencing syntax"),
 ]
)

As we can see, inventories contain a mapping of names to linkable locations relative to the root URL of a project's online documentation, see DocInventories.InventoryItem.

The DocInventories package provides tools for interactively searching inventories for items to reference. See Exploring Inventories and How do I figure out the correct name for the @extref link?.

Using External References

The DocumenterInterLinks plugin adds support for @extref link targets to Documenter. At the most fundamental level, they work just like Documenter's standard @ref link targets. Replacing @ref with @extref switches from a local reference to an external one:

* [`Documenter.makedocs`](@extref)
* [Documenter's `makedocs` function](@extref Documenter.makedocs)
* See the section about Documenter's [Writers](@extref).

The above markdown code renders as follows:

Documenter.makedocs
Documenter's makedocs function
See the section about Documenter's Writers.

To disambiguate (and speed up) the references, the name of the inventory (as defined when instantiating InterLinks) can be included in the @extref. In particular, the last example should have been written as

* See the section about Documenter's [Writers](@extref Documenter).

to clarify that we are linking to the section name "Writers" found in links["Documenter"]. When the link text and link target differ, the inventory name should be given between @extref and the target name, e.g., [`Regex`](@extref Julia Base.Regex), which turns into "Regex".

Since DocumenterInterLinks is fully compatible with Sphinx inventories, it also provides an extended @extref syntax that builds on the Sphinx concept of "domains" and "roles". You will see these when inspecting an InventoryItem:

using DocInventories

DocInventories.show_full(links["Documenter"]["Documenter.makedocs"])

InventoryItem(
  name="Documenter.makedocs",
  domain="jl",
  role="function",
  priority=1,
  uri="lib/public/#Documenter.makedocs",
  dispname="Documenter.makedocs"
)

We can include the domain and role in an @extref link as

* [`makedocs`](@extref :function:`Documenter.makedocs`)
* [`makedocs`](@extref :jl:function:`Documenter.makedocs`)

using a syntax that is reminiscent of the Sphinx cross-referencing syntax. The use of domains and roles in DocumenterInterLinks (unlike in Sphinx) is for disambiguation only, in case there are multiple items with the same name. In general, follow the Recommended Syntax guidelines.