Sphinx objects.inv v2 Syntax

After decompression, “version 2” Sphinx objects.inv files follow a syntax that, to the best of this author’s ability to determine, is not included in the Sphinx documentation. The below syntax is believed to be accurate as of Nov 2022 (Sphinx v6.0.0b2). It is based on inspection of objects.inv files “in the wild” and of the Sphinx inventory object parsing regex.

Based upon a quick git diff of the Sphinx repository, it is thought to be valid for all Sphinx versions >=1.0b1 that make use of this “version 2” objects.inv format.

NOTE that previous versions of the syntax presented here have been shown to be inaccurate:

  • It is permitted for the {name} field to contain whitespace (see #181).

  • It is permitted for the {role} field to contain a colon (see #256).

The descriptions below have been updated to reflect this and to provide more detailed information on the constraints governing each field of an objects.inv data line.

The first line must be exactly:

# Sphinx inventory version 2

The second and third lines must obey the template:

# Project: <project name>
# Version: <full version number>

The version number should not include a leading “v”.

The above project name and version are used to populate mouseovers for the intersphinx cross-references:

_images/mouseover_example.png

The fourth line must contain the string zlib somewhere within it, but for consistency it should be exactly:

# The remainder of this file is compressed using zlib.

All remaining lines of the file are the objects data, each laid out in the following syntax:

{name} {domain}:{role} {priority} {uri} {dispname}

{name}

The object name used when cross-referencing the object (falls between the backticks).

Constraints

  • MUST have nonzero length

  • MUST NOT start with #

  • SHOULD have no leading or trailing whitespace

  • MAY contain internal whitespace

{domain}

The Sphinx domain used when cross-referencing the object (falls between the first and second colons; omitted if using the default domain).

Constraints

  • MUST have nonzero length

  • MUST match a built-in or installable Sphinx domain

  • MUST NOT contain whitespace or a colon

    • RECOMMENDED to contain only ASCII word characters (a-z, A-Z, 0-9, and _)

{role}

The Sphinx role used when cross-referencing the object (falls between the second and third/last colons; or, between the first and second/last colons if using the default domain).

Note that the role MAY contain a colon, as occurs with the :rst:directive:option: directive in the Sphinx docs.

Constraints

  • MUST have nonzero length

  • MUST match a role defined in the domain referenced by {domain}

  • MUST NOT contain whitespace

    • RECOMMENDED to consist of only ASCII word characters (a-z, A-Z, 0-9, and _)

{priority}

Flag for placement in search results. Most will be 1 (standard priority) or -1 (omit from results) for documentation built by Sphinx; values of 0 (higher priority) or 2 (lower priority) may also occur.

To note, as of Jan 2022 this value is not used by intersphinx; it is only used internally within the search function of the static webpages built by Sphinx (here and here). Thus, custom inventories likely MAY use this field for arbitrary content, if desired, as long as the integer constraint is observed. Such use would run the risk of a future change to Sphinx/intersphinx breaking compatibility with objects.inv files having non-standard {priority} values.

Constraints

  • MUST have nonzero length

  • MUST be a positive or negative integer, or zero, without a decimal point

  • MUST NOT contain whitespace (implicit in the integer constraint)

{uri}

Relative URI for the location to which cross-references will point. The base URI is taken from the relevant element of the intersphinx_mapping configuration parameter in conf.py.

Constraints

  • MAY have zero length, but typically has nonzero length

  • MUST NOT contain whitespace

{dispname}

Default cross-reference text to be displayed in compiled documentation.

Constraints

  • MUST have nonzero length

  • MAY contain internal whitespace (leading/trailing whitespace is ignored)

Unicode characters appear to be valid for all fields except {uri} (where they are specifically forbidden) and {priority}. However, it is RECOMMENDED that they only be used in {dispname}, as their use in {name}, {domain} and {role} would complicate construction of cross-references from other documentation source.

For illustration, the following is the entry for the join() method of the str class in the Python 3.9 objects.inv, broken out field-by-field:

str.join py:method 1 library/stdtypes.html#$ -

{name}      = str.join
{domain}    = py
{role}      = method
{priority}  = 1
{uri}       = library/stdtypes.html#$
{dispname}  = -

The above illustrates two shorthand notations that were introduced to shrink the size of the inventory file:

  1. If {uri} has an anchor (technically a “fragment identifier,” the portion following the # symbol) and the tail of the anchor is identical to {name}, that tail is replaced with $.

  2. If {dispname} is identical to {name}, it is stored as -.

Thus, a standard intersphinx reference to this method would take the form:

:py:meth:`str.join`

The leading :py here could be omitted if py is the default domain.

The cross-reference would show as str.join() and link to the relative URI:

library/stdtypes.html#str.join

Other intersphinx Syntax Examples

To show as only join():

:py:meth:`~str.join`

To suppress the hyperlink as in str.join():

:py:meth:`!str.join`

To change the cross-reference text and omit the trailing parentheses as in This is join!:

:py:obj:`This is join! <str.join>`