Show/dump/browse/inspect an Intersphinx inventory

30 Aug '19

Intersphinx is a great extension to Python’s default (and awesome) Sphinx documentation generator. It allows you to link to other project’s documentation, including Python’s official documentation.

Sometimes, it’s rather tricky to figure out what reference exactly needs to be used.

Under the hood, Intersphinx uses compressed inventory files (*.inv, which are zip files in disguise). For example, Python’s official documentation is https://docs.python.org/3/, and that’s what you would put in your Sphinx conf.py configuration file:

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

Intersphinx will then load https://docs.python.org/3/objects.inv.

Luckily, Intersphinx provides a convenient method, inspect_main, to show/dump/browse/inspect an inventory, and an even handier entrypoint under sphinx.ext.intersphinx. There is one caveat; the file must be local. This is easily solved with curl (or wget if you prefer):

$ curl -L https://docs.python.org/3/objects.inv -o python3.inv
$ python3 -m sphinx.ext.intersphinx python3.inv | less

Naturally, Python’s documentation is extensive, so I would recommend piping to e.g. less.


One more thing to remember is Sphinx domains are tricky. The domain names - e.g. py:method - are not the same as the cross reference names - e.g. py:meth. With that in mind, I was able to find and link to Python’s documentation quickly.

Python

Newer Older