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
Or, if you only plan to use the sphobjinv CLI, another option is pipx
:
$ pipx install sphobjinv
As of Nov 2022, sphobjinv is also available via conda-forge. After activating the desired conda environment:
$ conda install -c conda-forge sphobjinv
Alternatively, sphobjinv is packaged with multiple POSIX distributions and package managers, including:
Alpine Linux:
py3-sphobjinv
(info)Arch Linux:
python-sphobjinv
(info)Fedora:
python-sphobjinv
(info)Gentoo:
dev-python/sphobjinv
(info)Guix:
python-sphobjinv
Manjaro:
python-sphobjinv
OpenEuler:
python-sphobjinv
openSUSE:
python-sphobjinv
(info)Parabola:
python-sphobjinv
(info)pkgsrc:
textproc/py-sphobjinv
(info)spack:
py-sphobjinv
(info)
sphobjinv is configured for use both as a command-line script and as a Python package.
The optional dependency python-Levenshtein
for accelerating
the “suggest” functionality is no longer available due to a
licensing conflict, and has been deprecated. See
here for more information.
The project source repository is on GitHub: bskinn/sphobjinv.