Sphinx Objects.inv Syntax¶
Plaintext 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 May 2016
(objects.inv
“version 2” files, Sphinx v1.4.1). Based upon
a quick git diff
of the Sphinx repository, it is thought to be accurate for all
Sphinx>=1.0b1.
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 ofconf.py
. {dispname}
- Default cross-reference text to be displayed in compiled documentation.
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>`