sphobjinv2.3.1.2
Published
Sphinx objects.inv Inspection/Manipulation Tool
pip install sphobjinv
Package Downloads
Authors
Requires Python
>=3.9
Dependencies
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, 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-2024
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.