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