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 completely undocumented. The below syntax is believed to be accurate as of Jun 2018 (Sphinx v1.7.4). Based upon a quick git diff of the Sphinx repository, it is thought to be accurate for all Sphinx versions >=1.0b1 that make use of this “version 2” objects.inv format.

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 above project name and version are used to populate mouseovers for the intersphinx cross-references:

The fourth line must contain the string ‘zlib’ somewhere in it, but for the purposes of 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)
{domain}: The Sphinx domain used when cross-referencing the object (falls between the first and second colons; omitted if using the default domain)
{role}: The Sphinx role used when cross-referencing the object (falls between the second and third colons; or, between the first and second colons if using the default domain)
{priority}: Flag for placement in search results. Most will be 1 (standard priority) or -1 (omit from results)
{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 of conf.py.
{dispname}: Default cross-reference text to be displayed in compiled documentation.

Note

The above fields MUST NOT contain spaces, except for {dispname} which MAY contain them.

For illustration, the following is the entry for the join() method of the str class in the Python 3.5 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:

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

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

Thus, a standard intersphinx reference to this method would take the form (the leading :py could be omitted if py is the default domain):

:py:meth:`str.join`

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>`