Skip to main content

Sphinx objects.inv Inspection/Manipulation Tool

Project description

sphobjinv: Manipulate and inspect Sphinx objects.inv files

Current Development Version

GitHub Workflow Status

Most Recent Stable Release

PyPI Version Python Versions

Info

ReadTheDocs status gitter chat

MIT License black formatted PePY stats


Using Sphinx?

Having trouble writing cross-references?

sphobjinv (short for 'sphinx objects.inv') can help!

The syntax required for a functional Sphinx cross-reference is non-obvious in many cases. Sometimes Sphinx can guess correctly what you mean, but it's pretty hit-or-miss. The best approach is to provide Sphinx with a completely specified cross-reference, and that's where sphobjinv comes in.

After a pip install sphobjinv (or pipx install sphobjinv), find the documentation set you want to cross-reference into, and pass it to sphobjinv suggest.

For internal cross-references, locate objects.inv within build/html:

$ sphobjinv suggest doc/build/html/objects.inv as_rst -st 58

------------------------------------------------

Cannot infer intersphinx_mapping from a local objects.inv.

------------------------------------------------

Project: sphobjinv
Version: 2.3

220 objects in inventory.

------------------------------------------------

11 results found at/above current threshold of 58.


  Name                                                Score
---------------------------------------------------  -------
:py:property:`sphobjinv.data.SuperDataObj.as_rst`      60
:py:class:`sphobjinv.cli.parser.PrsConst`              59
:py:class:`sphobjinv.data.DataFields`                  59
:py:class:`sphobjinv.data.DataObjBytes`                59
:py:class:`sphobjinv.data.DataObjStr`                  59
:py:class:`sphobjinv.data.SuperDataObj`                59
:py:class:`sphobjinv.enum.HeaderFields`                59
:py:class:`sphobjinv.enum.SourceTypes`                 59
:py:function:`sphobjinv.fileops.writebytes`            59
:py:function:`sphobjinv.fileops.writejson`             59
:py:class:`sphobjinv.inventory.Inventory`              59

The -s argument in the above shell command indicates to print the fuzzywuzzy match score along with each search result, and -t 50 changes the reporting threshold for the match score.

For external references, find the API documentation wherever it lives on the web, and pass sphobjinv suggest a URL from within the documentation set with the --url/-u flag. For example, say I need to know how to cross-reference the linspace function from numpy (see here):

$ sphobjinv suggest https://numpy.org/doc/1.26/reference/index.html linspace -su

Attempting https://numpy.org/doc/1.26/reference/index.html ...
  ... no recognized inventory.
Attempting "https://numpy.org/doc/1.26/reference/index.html/objects.inv" ...
  ... HTTP error: 404 Not Found.
Attempting "https://numpy.org/doc/1.26/reference/objects.inv" ...
  ... HTTP error: 404 Not Found.
Attempting "https://numpy.org/doc/1.26/objects.inv" ...
  ... inventory found.

----------------------------------------------------------------------------------

The intersphinx_mapping for this docset is LIKELY:

  (https://numpy.org/doc/1.26/, None)

----------------------------------------------------------------------------------

Project: NumPy
Version: 1.26

8152 objects in inventory.

----------------------------------------------------------------------------------

8 results found at/above current threshold of 75.

  Name                                                           Score
--------------------------------------------------------------  -------
:py:function:`numpy.linspace`                                     90
:py:method:`numpy.polynomial.chebyshev.Chebyshev.linspace`        90
:py:method:`numpy.polynomial.hermite.Hermite.linspace`            90
:py:method:`numpy.polynomial.hermite_e.HermiteE.linspace`         90
:py:method:`numpy.polynomial.laguerre.Laguerre.linspace`          90
:py:method:`numpy.polynomial.legendre.Legendre.linspace`          90
:py:method:`numpy.polynomial.polynomial.Polynomial.linspace`      90
:std:doc:`reference/generated/numpy.linspace`                     90

NOTE that the results from sphobjinv suggest are printed using the longer block directives, whereas cross-references must be composed using the inline directives. Thus, the above linspace() function must be cross-referenced as :func:`numpy.linspace` , not :function:`numpy.linspace`.

Need to edit an inventory after it's created, or compose one from scratch?

sphobjinv can help with that, too.

objects.inv files can be decompressed to plaintext at the commandline:

$ sphobjinv convert plain -o doc/build/html/objects.inv doc/scratch/
Conversion completed.
'...objects.inv' converted to '...objects.txt' (plain).

JSON output is supported (sphobjinv convert json ...), and inventories can be re-compressed to the partially-zlib-compressed form that intersphinx reads (sphobjinv convert zlib ...).

Alternatively, sphobjinv exposes an API to enable automation of inventory creation/modification:

>>> import sphobjinv as soi
>>> inv = soi.Inventory('doc/build/html/objects.inv')
>>> print(inv)
<Inventory (fname_zlib): sphobjinv v2.3, 220 objects>
>>> inv.project
'sphobjinv'
>>> inv.version
'2.3'
>>> inv.objects[0]
DataObjStr(name='sphobjinv.cli.convert', domain='py', role='module', priority='0', uri='cli/implementation/convert.html#module-$', dispname='-')

The API also enables straightforward re-export of an inventory, for subsequent use with intersphinx cross-references. See the docs for more details.


Full documentation is hosted at Read The Docs.

Available on PyPI (pip install sphobjinv).

Source on GitHub. Bug reports and feature requests are welcomed at the Issues page there.

Copyright (c) Brian Skinn 2016-2025

The sphobjinv documentation (including docstrings and README) is licensed under a Creative Commons Attribution 4.0 International License (CC-BY). The sphobjinv codebase is released under the MIT License. See LICENSE.txt for full license terms.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphobjinv-2.3.1.3.tar.gz (268.8 kB view details)

Uploaded Source

Built Distribution

sphobjinv-2.3.1.3-py3-none-any.whl (50.8 kB view details)

Uploaded Python 3

File details

Details for the file sphobjinv-2.3.1.3.tar.gz.

File metadata

  • Download URL: sphobjinv-2.3.1.3.tar.gz
  • Upload date:
  • Size: 268.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.10

File hashes

Hashes for sphobjinv-2.3.1.3.tar.gz
Algorithm Hash digest
SHA256 a1d51e4cf3d968b9e0d3ed1cbccea0071e5e5795f24a2d7401a4e37d6bd75717
MD5 3d9afcb198b0759617188a0fdd73aa79
BLAKE2b-256 779a4887ebe7b46f4669a896dc286a3ac559101d2ceadbbea4614472960c2222

See more details on using hashes here.

File details

Details for the file sphobjinv-2.3.1.3-py3-none-any.whl.

File metadata

  • Download URL: sphobjinv-2.3.1.3-py3-none-any.whl
  • Upload date:
  • Size: 50.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.10

File hashes

Hashes for sphobjinv-2.3.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 41fc39f6f740a707cfe5b24c1a3a4a6e4ddbdd6429a59bf21f0b5ef1fddf932a
MD5 d5e2ad971f65c6cba753993de5806f1f
BLAKE2b-256 63f9f48a8f489c8ae8930f12c558b4dd26da96791837747fca87e9da2643f12d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page