Interlinks filter

The interlinks filter allows you to provide crossreferences within and between documentation. It consists of three pieces:

1. Install: adding the extension to your quarto project.
2. Configure: specifying sphinx inventories for the filter to use in your _quarto.yml config.
3. Run: Generating sphinx inventories for the filter to use.

Installing

Use the quarto add command to install the interlinks filter:

quarto add machow/quartodoc

Note

The code for the filter can be found in quartodoc’s _extension folder

Configuring the interlinks filter

Configure the filter in _quarto.yml or on specific pages, by adding these sections:

filters:
  - interlinks

interlinks:
  sources:
    numpy:
      url: https://numpy.org/doc/stable/
    python:
      url: https://docs.python.org/3/
    quartodoc-test:
      url: https://machow.github.io/quartodoc
      inv: objects-test.txt

Notice 2 important pieces in this config:

• The numpy and python fields indicate that we’re getting inventories for the library numpy, and python builtin libraries.
• The url fields indicate where inventory files can be found.
• The inv field lets you specify the name of the inventory file. By default, it assumes its objects.inv.

By default, downloaded inventory files will be saved in the _inv folder of your documentation directory.

Experimental fast option

Use the experimental fast: true option to speed up the interlinks filter.

interlinks:
  fast: true
  sources:

By default inventory files are saved as JSON, but this option keeps them as text files, and attempts to parse them much faster.

Warning

Be sure to install the latest version of the interlinks filter, using quarto add machow/quartodoc.

Rendering interlinks in API docs

quartodoc can convert type annotations in function signatures to interlinks.

In order to enable this behavior, set render_interlinks: true in the quartodoc config.

quartodoc:
  render_interlinks: true

Running the interlinks filter

First, build the reference for your own site, which includes an objects.json inventory:

python -m quartodoc build

Second, retrieve the inventory files for any other sources:

python -m quartodoc interlinks

Finally you should see the filter run when previewing your docs:

quarto preview

Link formats

style	link text	syntax	output
manual		[a link](../api/#get_object)	a link
md	custom	[some explanation](`quartodoc.get_object`)	some explanation
md	default	[](`quartodoc.get_object`)	quartodoc.get_object
md	shortened	[](`~quartodoc.get_object`)	get_object

Link filtering syntax

Sometimes multiple documentation sites use the same target (e.g. function) names. The inventory format includes multiple pieces of information that can be used to refer to a specific entry in the inventory:

• inventory_name
• role: what kind of object is it? e.g. function, class.
• domain: what kind of piece of documentation is it? For example, "py" indicates it is a python function, and "c" indicates it’s a C function. This lets sites document libraries that are implemented in multiple languages.

Filtering by these pieces of information can be down using the following syntax:

:external+inventory_name:domain:role:`target`
:domain:role:`target`
:role:`target`
`target`

Notice that this syntax allows you to go from more specific information (i.e. `target` on the right), to least specific information (role, then domain).

In practice, it’s often enough to specify the role of a function, like:

• :function:`quartodoc.get_object`
• :class:`quartodoc.MdRenderer`

Example: python.org print

For example, python.org has two entries for the name print.

domain	role	link syntax
std	2to3fixer	[](:std:2to3fixer:`print`)
py	function	[](:py:function:`print`)

What is a sphinx inventory file?

Sphinx inventory files provide information about where the documentation for functions live on a website.

Most sphinx sites name them object.inv:

• numpy: https://numpy.org/doc/stable/objects.inv
• python: https://docs.python.org/3/objects.inv

See the sphobjinv docs for thorough details on these files, and how they’re used in sphinx.

Note

objects-test.txt is an example file with one entry: qd2.Auto.

More information

Under the hood, quarto doc generates sphinx inventories for an API e using create_inventory, and then dumps it to JSON using convert_inventory.

For an overview of the sphinx inventory format, see the sphobjinv docs.

The rough idea is that this plugin will behave similar to jupyterbook linking, which supports both some intersphinx syntax, but also markdown syntax.