1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
## sphobjinv: Manipulate and inspect Sphinx objects.inv files
#### Current Development Version
[![GitHub Workflow Status][workflow badge]][workflow link target]
#### Most Recent Stable Release
[![PyPI Version][pypi badge]][pypi link target]
![Python Versions][python versions badge]
#### Info
[![ReadTheDocs status][readthedocs badge]][readthedocs link target]
[![gitter chat][gitter badge]][gitter link target]
[![MIT License][license badge]][license link target]
[![black formatted][black badge]][black link target]
[![PePY stats][pepy badge]][pepy link target]
----
### Using Sphinx?
#### Having trouble writing cross-references?
`sphobjinv` (short for '**sph**inx **obj**ects.**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`:
```none
$ 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][numpy linspace]):
```none
$ 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:
```none
$ 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:
```python
>>> 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][soi docs inv export] for
more details.
----
Full documentation is hosted at [Read The Docs][readthedocs link target].
Available on [PyPI][pypi link target] (`pip install sphobjinv`).
Source on [GitHub][github repo]. Bug reports and feature requests are welcomed
at the [Issues][github issue tracker] 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 4.0]
(CC-BY). The `sphobjinv` codebase is released under the [MIT License]. See
[`LICENSE.txt`][license link target] for full license terms.
[black badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black link target]: https://github.com/psf/black
[cc-by 4.0]: http://creativecommons.org/licenses/by/4.0/
[soi docs inv export]: http://sphobjinv.readthedocs.io/en/latest/api_usage.html#exporting-an-inventory
[github issue tracker]: https://github.com/bskinn/sphobjinv/issues
[github repo]: https://github.com/bskinn/sphobjinv
[gitter badge]: https://badges.gitter.im/sphobjinv/community.svg
[gitter link target]: https://gitter.im/sphobjinv/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
[license badge]: https://img.shields.io/github/license/mashape/apistatus.svg
[license link target]: https://github.com/bskinn/sphobjinv/blob/stable/LICENSE.txt
[mit license]: https://opensource.org/licenses/MIT
[numpy linspace]: https://numpy.org/doc/1.26/reference/generated/numpy.linspace.html
[pepy badge]: https://pepy.tech/badge/sphobjinv/month
[pepy link target]: https://pepy.tech/projects/sphobjinv?timeRange=threeMonths&category=version&includeCIDownloads=true&granularity=daily&viewType=chart&versions=2.0.*%2C2.1.*%2C2.2.*%2C2.3.*
[pypi badge]: https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi]
[pypi link target]: https://pypi.org/project/sphobjinv
[python versions badge]: https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python
[readthedocs badge]: https://img.shields.io/readthedocs/sphobjinv/latest.svg
[readthedocs link target]: http://sphobjinv.readthedocs.io/en/latest/
[workflow badge]: https://img.shields.io/github/actions/workflow/status/bskinn/sphobjinv/ci_tests.yml?logo=github&branch=main
[workflow link target]: https://github.com/bskinn/sphobjinv/actions
|
