Fallback Resolution

Warning

The ExternalFallbacks plugin described here is available only with Documenter >= v1.3.0 and should be considered experimental.

In some situations, you may need to include a docstring from an external package in your documentation – for example, you you are extending a function from that package, you may want to show the function docstring. If that docstrings contains an @ref link, you have a problem: that link is resolvable in the external documentation, but not in your documentation.

If the @ref link is to another code object, you could include that docstring in your documentation as well, and so forth, until all references can be resolved. Unfortunately, you might end up having to include a significant portion of the external package's documentation, which is less than ideal.

The situation is even worse if the @ref link is to a section header. For example, the docstring of DocInventories.MIME_TYPES includes a reference to the section on inventory file formats in the DocInventories documentation. In that case, there is no way to make the reference resolve in your documentation (short of adding an "Inventory File Formats" section to your own documentation).

To remedy this, the DocumenterInterLinks package provides a special plugin, ExternalFallbacks, that can rewrite specific @ref links to @extref links. It is instantiated by providing a mapping between "slugs" and @extref link specifications. For example,

fallbacks = ExternalFallbacks(
    "Inventory-File-Formats" => "@extref DocInventories `Inventory-File-Formats`",
)

Warning

Like any plugin, fallbacks must be passed to Documenter.makedocs as an element of plugins.

The "slug" on the left-hand-side of the mapping can be obtained from the message that Documenter prints when it fails to resolve the @ref link. Generally, for [Section Title](@ref) or [text](@ref "Section Title), the slug is a "sluggified" version of the title (determined internally by Documenter, mostly just replacing spaces with dashes); and for [`code`](@ref) or [text](@ref code), it is "code". The right-hand-side of the mapping is a full @extref link. The plugin simply replaces the link target of original @ref link with the given @extref.

If there are any unresolvable @ref links, and there is no explicit @extref-mapping, ExternalFallbacks will search in all available inventories to resolve the link in an "automatic" mode. In this case, you will see messages like

[ Info: ExternalFallbacks automatic resolution of "Inventory-File-Formats" => "@extref DocInventories :std:label:`Inventory-File-Formats`"

in the output of Documenter.makedocs. If this is correct, you should copy "Inventory-File-Formats" => "@extref DocInventories :std:label:`Inventory-File-Formats`" explicitly into the instantiation of the ExternalFallbacks plugin. The "automatic resolution" is both slow and has the potential for misidentifying the @extref link.

Warning

Do not use @ref links in your documentation for known @extref targets! The ExternalFallbacks plugin is intended as a "last resort", to be used deliberately, not to automatically resolve all @ref links via InterLinks.

With an @extref mapping for "Inventory-File-Formats" in place, it is now possible to include the docstring for DocInventories.MIME_TYPES:

DocInventories.MIME_TYPES — Constant

Default map of file extensions to MIME types.

MIME_TYPES = Dict(
    ".txt" => MIME("text/x-intersphinx"),
    ".inv" => MIME("application/x-intersphinx"),
    ".toml" => MIME("application/toml"),
    ".txt.gz" => MIME("text/x-intersphinx+gzip"),
    ".toml.gz" => MIME("application/toml+gzip"),
)

See Inventory File Formats for details.

source

Note that the link in the last line of the docstring is an external link.