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:
Searching and inspection of objects.inv contents in order to identify how to properly construct
intersphinx
references.
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.