DocumenterInterLinks.jl

A plugin for Documenter.jl that enables linking between projects.

The package provides an InterLinks plugin that loads inventory files from other project documentations built with Documenter or Sphinx. It then extends Documenter's markdown link syntax to recognize an @extref link target and resolve it with a link to the external project (similarly to the built-in @ref links for internal links), see External References.

Installation

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).

Plugin Instantiation

In docs/make.jl, instantiate an InterLinks object, e.g.,

using DocumenterInterLinks

links = InterLinks(
    "matplotlib" => "https://matplotlib.org/3.7.3/",
    "sphinx" => "https://www.sphinx-doc.org/en/master/",
)

See docs/make.jl for another example.

The resulting plugin object must be passed as an element of the plugins keyword argument to Documenter.makedocs. This then enables @extref links in the project's documentation to be resolved.

See docs/src/inventories for some exemplary inventory files in the TOML format.

External References

Instead of Documenter's @ref, the @extref link target can be used to resolve the link via any of the available projects defined in the InterLinks plugin:

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

See the documentation and recommended syntax for details.

Inventories

Inventory files (objects.inv) are automatically generated by Documenter.jl ≥ v1.3.0 and Sphinx. For projects using Documenter v0.25.0–v1.2.0 , the DocumenterInventoryWritingBackport package provides a backport of the inventory-writing functionality. For these projects, simply loading DocumenterInventoryWritingBackport in the docs/make.jl file will ensure the creation of a objects.inv file.

For some projects that do not (or not yet) provide an inventory, manually generated inventory files in human-readable .toml format are collected in the Inventory File Repository (Wiki). Feel free to generate your own inventory files and contribute them. These .toml files can be copied to the source of your project's documentation, and loaded in the InterLinks plugin as local sources of inventory information.

Documentation

The full documentation of this project is available online.

Related Projects

• DocInventories.jl – The backend used for processing inventory files, e.g., the objects.inv file generated by Documenter.jl and Sphinx.
• The Intersphinx plugin for Sphinx – The Python-equivalent of this project.