Welcome to sphobjinv!

A toolkit for inspection/manipulation of Sphinx objects inventories

When documentation is built using, e.g., Sphinx’s StandaloneHTMLBuilder, an inventory of the named objects in the documentation set is dumped to a file called objects.inv in the html build directory. (One common location is, doc/build/html, though the exact location will vary depending on the details of how Sphinx is configured.) This file is read by intersphinx when generating links in other documentation.

Since version 1.0 of Sphinx (~July 2010), the data in these objects.inv inventories is compressed by zlib (presumably to reduce storage requirements and improve download speeds; “version 2”), whereas prior to that date the data was left uncompressed (“version 1”). This compression renders the files non-human-readable. It is the purpose of this package to enable quick and simple compression/decompression and inspection of these “version 2” inventory files.

In particular, sphobjinv was developed to satisfy two primary use cases:

  1. Searching and inspection of objects.inv contents in order to identify how to properly construct intersphinx references.

  2. Assembly of new objects.inv files in order to allow intersphinx cross-referencing of other documentation sets that were not created by Sphinx.

For more background on the mechanics of the Sphinx data model and Sphinx cross-references generally, see this talk from PyOhio 2019.

Install sphobjinv via pip:

$ pip install sphobjinv

Alternatively, sphobjinv is packaged with multiple POSIX distributions, including:

  • Alpine Linux: py3-sphobjinv (info)

  • Arch Linux: python-sphobjinv (info)

  • Fedora: python-sphobjinv (info)

  • Gentoo GURU: dev-python/sphobjinv (info)

  • Manjaro: python-sphobjinv

  • OpenEuler: python-sphobjinv

  • openSUSE: python-sphobjinv (info)

  • Parabola: python-sphobjinv (info)

  • pkgsrc: textproc/py-sphobjinv (info)

The package is configured for use both as a command-line script and as a Python package.

Installing the optional dependency python-Levenshtein substantially accelerates the the “suggest” functionality; see here for more information.

The project source repository is on GitHub: bskinn/sphobjinv.

Indices and Tables

Logo adapted from freely-available image at https://heypik.com/images/hand-drawn-cartoon-color-tourist-attraction-sphinx_8ZU4501.html (retrieved July 2019; now defunct).