Skip to content
Toolkit for manipulation and inspection of Sphinx objects.inv files
Python
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Add explicit long-description content type flag Jan 26, 2020
src/sphobjinv Bump version and copyright years Jan 26, 2020
tests Bump version and copyright years Jan 26, 2020
.coveragerc TEST: Switch to stdio_mgr for cli tests Jan 21, 2018
.gitignore TEST/ADMIN: Update .gitignore, conf.py, README Jun 7, 2019
.readthedocs.yml Add basic .readthedocs.yml Jan 27, 2020
.travis.yml Switch travis doctest to py3.7 Jan 26, 2020
AUTHORS.md Draft AUTHORS.md Jan 27, 2020
CHANGELOG.md
LICENSE.txt Bump version and copyright years Jan 26, 2020
MANIFEST.in
README.rst Update README badges and CHANGELOG Jan 27, 2020
conftest.py Bump version and copyright years Jan 26, 2020
pyproject.toml MASSIVE: Revise testing, deps, admin stuff Apr 1, 2019
requirements-dev.txt Update Sphinx to 2.3.1 Jan 26, 2020
requirements-flake8.txt
requirements-rtd.txt Update Sphinx to 2.3.1 Jan 26, 2020
requirements-travis.txt Update Sphinx to 2.3.1 Jan 26, 2020
setup.py Add explicit long-description content type flag Jan 26, 2020
tox.ini Freshen tox env dependency versions Jan 25, 2020

README.rst

sphobjinv: Manipulate and inspect Sphinx objects.inv files

Current Development Version:

https://img.shields.io/travis/com/bskinn/sphobjinv?label=travis-ci&logo=travis

Most Recent Stable Release:

https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi

https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python

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, 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 50

  Name                                                     Score
--------------------------------------------------------  -------
:py:method:`sphobjinv.data.SuperDataObj.as_rst`             60
:py:function:`sphobjinv.cmdline.getparser`                  50
:py:method:`sphobjinv.data.SuperDataObj.as_str`             50
:py:method:`sphobjinv.inventory.Inventory.objects_rst`      50

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 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 Axis class from matplotlib (see here):

$ sphobjinv suggest https://matplotlib.org/api/ticker_api.html axis -su

No inventory at provided URL.
Attempting "https://matplotlib.org/api/ticker_api.html/objects.inv" ...
Attempting "https://matplotlib.org/api/objects.inv" ...
Attempting "https://matplotlib.org/objects.inv" ...
Remote inventory found.


  Name                           Score
------------------------------  -------
:py:module:`matplotlib.axis`      90
:std:doc:`api/axis_api`           90
:std:label:`axis-container`       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 redirect() function must be cross-referenced as :func:`flask.redirect`, not :function:`flask.redirect`.

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.0, 181 objects>
>>> inv.project
'sphobjinv'
>>> inv.version
'2.0'
>>> inv.objects[0]
DataObjStr(name='sphobjinv.cmdline', domain='py', role='module', priority='0', uri='cli/implementation.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-2020

License: The MIT License. See LICENSE.txt for full license terms.

You can’t perform that action at this time.