Intersphinx examples

Copy a reference and compare its destination below. These examples cover native language roles, portable labels, full and scoped inventories, and links into tmux C declarations, hooks, format variables and CLI commands.

Configure the inventories¶

Add these mappings to your Sphinx project’s conf.py:

None discovers objects.inv at the mapping’s base URL. The full inventory uses each port’s advertised default version. The py mapping explicitly selects latest; tmux selects the latest tmux manual and C reference. Use the root URL from an inventory’s footer link when selecting a preview or another release.

Native Python roles¶

A named inventory selects the Python tree:

:external+py:py:class:`libtmux.Pane`

Destination: CPane.

The full inventory qualifies native names by port:

:external+full:py:class:`py:libtmux.Pane`

Destination: Pane in the Python default version.

For automatic lookup, use the ordinary role. A local definition takes precedence over Intersphinx:

:py:class:`libtmux.Pane`

Destination: Pane.

Portable labels¶

Portable labels work with the standard reference role, including languages that have no built-in Sphinx domain. Copy the key from targets.json.

:external+full:ref:`Pane <py:core:api:libtmux.%50ane>`
:external+py:ref:`Pane <py:core:api:libtmux.%50ane>`

Destinations: Full inventory: Pane, CScoped inventory: Pane.

The external role searches the configured inventories without selecting one. This native name is unqualified only in the scoped Python inventory:

:external:py:class:`libtmux.Pane`

Destination: Pane.

MyST roles and inventory URLs¶

Enable myst_parser alongside sphinx.ext.intersphinx for Markdown sources. Named roles accept the same targets as reStructuredText:

{external+py:py:class}`libtmux.Pane`

Destination: CPane.

Portable labels retain their percent escapes inside reference roles:

{external+full:ref}`Pane <py:core:api:libtmux.%50ane>`

Destination: Pane in the Python default version.

MyST’s inventory URL syntax also supports native aliases:

[Pane](inv:py:py:class#libtmux.Pane)

Destination: Pane.

Use role syntax for percent-encoded portable keys: MyST normalizes escapes in inv: URLs. Keep mapping names free of dots, as in tmux-3-7c, so MyST can parse the role name. When using an inventory URL, specify its domain and object type if a name is both a document and a label.

tmux C declarations¶

The tmux mapping provides Sphinx’s built-in C roles:

:external+tmux:c:struct:`cmd`
:external+tmux:c:func:`cmd_find_target`

Destinations: cmd, cmd_find_target.

Select a release with its own mapping. The full inventory also offers version-qualified native aliases:

:external+tmux-3-7c:c:func:`cmd_find_target`
:external+full:c:func:`tmux@3.7c:cmd_find_target`
:external+full:c:func:`tmux@latest:cmd_find_target`

Destinations: Scoped: cmd_find_target in 3.7c, Full: cmd_find_target in 3.7c, Full: cmd_find_target in latest.

MyST supports the same C roles and a typed inventory URL:

{external+tmux:c:struct}`cmd`
{external+tmux:c:func}`cmd_find_target`
{external+full:c:func}`tmux@3.7c:cmd_find_target`
[cmd_find_target](inv:tmux:c:function#cmd_find_target)

Destinations: MyST: cmd, MyST: cmd_find_target, MyST full: cmd_find_target in 3.7c, Inventory URL: cmd_find_target.

The C reference links each declaration to its source file and revision. Portable labels also address its signatures, parameters, and sections.

tmux hooks¶

Link a hook name to its catalog page with a portable label. The same key works in the scoped tmux inventory and the full inventory:

:external+tmux:ref:`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
:external+full:ref:`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`

Destinations: Scoped: after-new-session, Full: after-new-session.

In MyST, use the same key inside a reference role. Preserve its percent escapes:

{external+tmux:ref}`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`
{external+full:ref}`after-new-session <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fhooks%2fafter-new-session>`

Destinations: MyST scoped: after-new-session, MyST full: after-new-session.

tmux formats¶

Link a format variable such as ##{session_name} to its catalog entry:

:external+tmux:ref:`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
:external+full:ref:`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`

Destinations: Scoped: session_name, Full: session_name.

The MyST references select the same scoped or full inventory:

{external+tmux:ref}`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`
{external+full:ref}`session_name <tmux%40latest:core:doc:tmux%2flatest%2fcatalog%2fformats%2fsession_name>`

Destinations: MyST scoped: session_name, MyST full: session_name.

tmux CLI manual¶

The same tmux inventory covers command pages:

:external+tmux:ref:`capture-pane <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fcapture-pane>`

Destination: capture-pane.

The document role works when the target is a whole page:

:external+tmux:doc:`Full manual <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2ffull>`

Destination: Full tmux manual.

Select a command’s manual page with the document role. Its portable key also works in the full inventory:

:external+tmux:doc:`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
:external+full:doc:`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`

Destinations: Scoped: new-session, Full: new-session.

Use the same document role in MyST:

{external+tmux:doc}`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`
{external+full:doc}`tmux new-session <tmux%40latest:core:doc:tmux%2flatest%2fmanual%2fnew-session>`

Destinations: MyST scoped: new-session, MyST full: new-session.

Command options, environment variables, and terms¶

The Python port’s workspace documentation exports standard-domain objects. Set the program context before referencing an option:

.. program:: tmuxp load

:external+py:option:`--append`

Destination: tmuxp load —append.

Environment variables and glossary terms use their own roles. Qualify the product when a term appears in more than one glossary:

:external+py:envvar:`COLUMNS`
:external+py:term:`async <py:core:async>`

Destinations: COLUMNS, async.

MCP tools and schema fields¶

Portable labels also address protocol objects and individual JSON Schema fields. No custom MCP domain is required:

{external+py:ref}`Read tools batch <py:mcp:tool:call_read_tools_batch>`
{external+py:ref}`on_error <py:mcp:schema:mcp.tool.call_read_tools_batch.input%2fproperties%2fon_error>`

Destinations: tRead tools batch, on_error.

Shared documentation and headings¶

The full inventory includes the shared documentation:

:external+full:doc:`Inventory guide <site:core:doc:intersphinx>`
:external+full:ref:`Configure Intersphinx <site:core:heading:intersphinx%23configure-intersphinx>`

Destinations: Inventory guide, Configure Intersphinx.

Local files and fallback locations¶

Download an inventory and pass its filename as the second mapping value. The first value remains the documentation URL used in generated links:

An ordered list tries a local copy before the HTTP inventory:

See the inventory guide for key stability and the Sphinx Intersphinx reference for configuration options.