## sphobjinv: Manipulate and inspect Sphinx objects.inv files
#### Current Development Version
[![GitHub Workflow Status][workflow badge]][workflow link target]
[![Codecov Coverage][codecov badge]][codecov 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 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`:
```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-2024
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/
[codecov badge]: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg
[codecov target]: https://codecov.io/gh/bskinn/sphobjinv
[soi docs inv export]: http://sphobjinv.readthedocs.io/en/v2.3.1.1/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/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1
[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/v2.3.1.1.svg
[readthedocs link target]: http://sphobjinv.readthedocs.io/en/v2.3.1.1/
[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
Raw data
{
"_id": null,
"home_page": null,
"name": "sphobjinv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sphinx, sphinx-doc, inventory, manager, inspector",
"author": null,
"author_email": "Brian Skinn <brian.skinn@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/04/b6/1b601e15bd109d0c5314c8c346d3b04f7de516c9622ac3e5c2d4ef9010da/sphobjinv-2.3.1.1.tar.gz",
"platform": "any",
"description": "## sphobjinv: Manipulate and inspect Sphinx objects.inv files\n\n\n#### Current Development Version\n\n[![GitHub Workflow Status][workflow badge]][workflow link target]\n[![Codecov Coverage][codecov badge]][codecov target]\n\n#### Most Recent Stable Release\n\n[![PyPI Version][pypi badge]][pypi link target]\n![Python Versions][python versions badge]\n\n#### Info\n\n[![ReadTheDocs status][readthedocs badge]][readthedocs link target]\n[![gitter chat][gitter badge]][gitter link target]\n\n[![MIT License][license badge]][license link target]\n[![black formatted][black badge]][black link target]\n[![PePY stats][pepy badge]][pepy link target]\n\n----\n\n### Using Sphinx?\n\n#### Having trouble writing cross-references?\n\n`sphobjinv` (short for '**sph**inx **obj**ects.**inv**') can help!\n\nThe syntax required for a functional Sphinx cross-reference is highly\nnon-obvious in many cases. Sometimes Sphinx can guess correctly what\nyou mean, but it's pretty hit-or-miss. The best approach is to provide\nSphinx with a completely specified cross-reference, and that's where\n`sphobjinv` comes in.\n\nAfter a `pip install sphobjinv` (or `pipx install sphobjinv`), find the\ndocumentation set you want to cross-reference into, and pass it to\n`sphobjinv suggest`.\n\nFor internal cross-references, locate `objects.inv` within `build/html`:\n\n```none\n$ sphobjinv suggest doc/build/html/objects.inv as_rst -st 58\n\n------------------------------------------------\n\nCannot infer intersphinx_mapping from a local objects.inv.\n\n------------------------------------------------\n\nProject: sphobjinv\nVersion: 2.3\n\n220 objects in inventory.\n\n------------------------------------------------\n\n11 results found at/above current threshold of 58.\n\n\n Name Score\n--------------------------------------------------- -------\n:py:property:`sphobjinv.data.SuperDataObj.as_rst` 60\n:py:class:`sphobjinv.cli.parser.PrsConst` 59\n:py:class:`sphobjinv.data.DataFields` 59\n:py:class:`sphobjinv.data.DataObjBytes` 59\n:py:class:`sphobjinv.data.DataObjStr` 59\n:py:class:`sphobjinv.data.SuperDataObj` 59\n:py:class:`sphobjinv.enum.HeaderFields` 59\n:py:class:`sphobjinv.enum.SourceTypes` 59\n:py:function:`sphobjinv.fileops.writebytes` 59\n:py:function:`sphobjinv.fileops.writejson` 59\n:py:class:`sphobjinv.inventory.Inventory` 59\n```\n\nThe `-s` argument in the above shell command indicates to print the\n`fuzzywuzzy` match score along with each search result, and `-t 50`\nchanges the reporting threshold for the match score.\n\nFor external references, find the API documentation wherever it lives on\nthe web, and pass `sphobjinv suggest` a URL from within the documentation set\nwith the `--url/-u` flag. For example, say I need to know how to\ncross-reference the `linspace` function from numpy (see\n[here][numpy linspace]):\n\n```none\n$ sphobjinv suggest https://numpy.org/doc/1.26/reference/index.html linspace -su\n\nAttempting https://numpy.org/doc/1.26/reference/index.html ...\n ... no recognized inventory.\nAttempting \"https://numpy.org/doc/1.26/reference/index.html/objects.inv\" ...\n ... HTTP error: 404 Not Found.\nAttempting \"https://numpy.org/doc/1.26/reference/objects.inv\" ...\n ... HTTP error: 404 Not Found.\nAttempting \"https://numpy.org/doc/1.26/objects.inv\" ...\n ... inventory found.\n\n----------------------------------------------------------------------------------\n\nThe intersphinx_mapping for this docset is LIKELY:\n\n (https://numpy.org/doc/1.26/, None)\n\n----------------------------------------------------------------------------------\n\nProject: NumPy\nVersion: 1.26\n\n8152 objects in inventory.\n\n----------------------------------------------------------------------------------\n\n8 results found at/above current threshold of 75.\n\n Name Score\n-------------------------------------------------------------- -------\n:py:function:`numpy.linspace` 90\n:py:method:`numpy.polynomial.chebyshev.Chebyshev.linspace` 90\n:py:method:`numpy.polynomial.hermite.Hermite.linspace` 90\n:py:method:`numpy.polynomial.hermite_e.HermiteE.linspace` 90\n:py:method:`numpy.polynomial.laguerre.Laguerre.linspace` 90\n:py:method:`numpy.polynomial.legendre.Legendre.linspace` 90\n:py:method:`numpy.polynomial.polynomial.Polynomial.linspace` 90\n:std:doc:`reference/generated/numpy.linspace` 90\n```\n\n**NOTE** that the results from `sphobjinv suggest` are printed using the\nlonger *block directives*, whereas cross-references must be composed using the\n*inline directives*. Thus, the above `linspace()` function must be\ncross-referenced as ``` :func:`numpy.linspace` ``` , **not**\n``` :function:`numpy.linspace` ```.\n\n**Need to edit an inventory after it's created, or compose one from scratch?**\n\n`sphobjinv` can help with that, too.\n\n`objects.inv` files can be decompressed to plaintext at the commandline:\n\n```none\n$ sphobjinv convert plain -o doc/build/html/objects.inv doc/scratch/\nConversion completed.\n'...objects.inv' converted to '...objects.txt' (plain).\n```\n\nJSON output is supported (`sphobjinv convert json ...`), and\ninventories can be re-compressed to the\npartially-zlib-compressed form that `intersphinx` reads\n(`sphobjinv convert zlib ...`).\n\nAlternatively, `sphobjinv` exposes an API to enable automation of\ninventory creation/modification:\n\n```python\n>>> import sphobjinv as soi\n>>> inv = soi.Inventory('doc/build/html/objects.inv')\n>>> print(inv)\n<Inventory (fname_zlib): sphobjinv v2.3, 220 objects>\n>>> inv.project\n'sphobjinv'\n>>> inv.version\n'2.3'\n>>> inv.objects[0]\nDataObjStr(name='sphobjinv.cli.convert', domain='py', role='module', priority='0', uri='cli/implementation/convert.html#module-$', dispname='-')\n\n```\n\nThe API also enables straightforward re-export of an inventory, for subsequent\nuse with `intersphinx` cross-references. See [the docs][soi docs inv export] for\nmore details.\n\n----\n\nFull documentation is hosted at [Read The Docs][readthedocs link target].\n\nAvailable on [PyPI][pypi link target] (`pip install sphobjinv`).\n\nSource on [GitHub][github repo]. Bug reports and feature requests are welcomed\nat the [Issues][github issue tracker] page there.\n\nCopyright (c) Brian Skinn 2016-2024\n\nThe `sphobjinv` documentation (including docstrings and README) is licensed\nunder a [Creative Commons Attribution 4.0 International License][cc-by 4.0]\n(CC-BY). The `sphobjinv` codebase is released under the [MIT License]. See\n[`LICENSE.txt`][license link target] for full license terms.\n\n\n[black badge]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black link target]: https://github.com/psf/black\n[cc-by 4.0]: http://creativecommons.org/licenses/by/4.0/\n[codecov badge]: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg\n[codecov target]: https://codecov.io/gh/bskinn/sphobjinv\n[soi docs inv export]: http://sphobjinv.readthedocs.io/en/v2.3.1.1/api_usage.html#exporting-an-inventory\n[github issue tracker]: https://github.com/bskinn/sphobjinv/issues\n[github repo]: https://github.com/bskinn/sphobjinv\n[gitter badge]: https://badges.gitter.im/sphobjinv/community.svg\n[gitter link target]: https://gitter.im/sphobjinv/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n[license badge]: https://img.shields.io/github/license/mashape/apistatus.svg\n[license link target]: https://github.com/bskinn/sphobjinv/blob/stable/LICENSE.txt\n[mit license]: https://opensource.org/licenses/MIT\n[numpy linspace]: https://numpy.org/doc/1.26/reference/generated/numpy.linspace.html\n[pepy badge]: https://pepy.tech/badge/sphobjinv/month\n[pepy link target]: https://pepy.tech/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1\n[pypi badge]: https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi]\n[pypi link target]: https://pypi.org/project/sphobjinv\n[python versions badge]: https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python\n[readthedocs badge]: https://img.shields.io/readthedocs/sphobjinv/v2.3.1.1.svg\n[readthedocs link target]: http://sphobjinv.readthedocs.io/en/v2.3.1.1/\n[workflow badge]: https://img.shields.io/github/actions/workflow/status/bskinn/sphobjinv/ci_tests.yml?logo=github&branch=main\n[workflow link target]: https://github.com/bskinn/sphobjinv/actions\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Sphinx objects.inv Inspection/Manipulation Tool",
"version": "2.3.1.1",
"project_urls": {
"Changelog": "https://github.com/bskinn/sphobjinv/blob/main/CHANGELOG.md",
"Docs": "https://sphobjinv.readthedocs.io/en/stable/",
"Donate": "https://github.com/sponsors/bskinn",
"Homepage": "https://github.com/bskinn/sphobjinv",
"Thank": "https://fosstodon.org/@btskinn"
},
"split_keywords": [
"sphinx",
" sphinx-doc",
" inventory",
" manager",
" inspector"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0ed3e44fb29ed17193f83ca0dbbb5393ff4a96070b3477d932efc577f24dc1f",
"md5": "5081eaeff0838c585cc96048d1b25f6e",
"sha256": "d6b4c22d73c2f757794a76f6d32850804062fdc1b4530f35f6c53891fe5ec943"
},
"downloads": -1,
"filename": "sphobjinv-2.3.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5081eaeff0838c585cc96048d1b25f6e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 50750,
"upload_time": "2024-05-22T03:41:14",
"upload_time_iso_8601": "2024-05-22T03:41:14.780536Z",
"url": "https://files.pythonhosted.org/packages/f0/ed/3e44fb29ed17193f83ca0dbbb5393ff4a96070b3477d932efc577f24dc1f/sphobjinv-2.3.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04b61b601e15bd109d0c5314c8c346d3b04f7de516c9622ac3e5c2d4ef9010da",
"md5": "77130e184f67bc231bae631609b263a3",
"sha256": "47c603fefd3150fd594b3c68feabfaa1d28f4a67b703494154cac8a7447aa483"
},
"downloads": -1,
"filename": "sphobjinv-2.3.1.1.tar.gz",
"has_sig": false,
"md5_digest": "77130e184f67bc231bae631609b263a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 267053,
"upload_time": "2024-05-22T03:41:27",
"upload_time_iso_8601": "2024-05-22T03:41:27.890495Z",
"url": "https://files.pythonhosted.org/packages/04/b6/1b601e15bd109d0c5314c8c346d3b04f7de516c9622ac3e5c2d4ef9010da/sphobjinv-2.3.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-22 03:41:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bskinn",
"github_project": "sphobjinv",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "sphobjinv"
}
JSON
