sphobjinv: Manipulate and inspect Sphinx objects.inv files

Current Development Version:

Most Recent Stable Release:

Info:

---

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 highly 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, just 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.23/reference/index.html linspace -su

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

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

The intersphinx_mapping for this docset is LIKELY:

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

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

Project: NumPy
Version: 1.23

8074 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?**sphobjinvcan help with that, too.objects.invfiles 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). .. end shell command JSON output is supported (sphobjinv convert json ...), and inventories can be re-compressed to the partially-zlib-compressed form thatintersphinxreads (sphobjinv convert zlib ...). Alternatively,sphobjinvexposes 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 withintersphinxcross-references. See `the docs <http://sphobjinv.readthedocs.io/en/latest/ api_usage.html#exporting-an-inventory>`__ for more details. ---- Full documentation is hosted at `Read The Docs <http://sphobjinv.readthedocs.io/en/latest/>`__. Available on `PyPI <https://pypi.org/project/sphobjinv>`__ (pip install sphobjinv). Source on `GitHub <https://github.com/bskinn/sphobjinv>`__. Bug reports and feature requests are welcomed at the `Issues <https://github.com/bskinn/sphobjinv/issues>`__ page there. Copyright (c) Brian Skinn 2016-2022 Thesphobjinvdocumentation (including docstrings and README) is licensed under a `Creative Commons Attribution 4.0 International License <http://creativecommons.org/licenses/by/4.0/>`__ (CC-BY). Thesphobjinv` codebase is released under the `MIT License <https://opensource.org/licenses/MIT>__. See LICENSE.txt for full license terms.