# 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

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`

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

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.

## Indices and Tables

Index — Module Index — Search Page