New release of sphinx-hoverxref with support for intersphinx

2021-06-10T00:00:00+00:00

We have released version 0.6b1 of sphinx-hoverxref, a Sphinx extension that shows a content preview of a cross-reference.

This extension is an essential part of the work we are doing to improve interoperability of documentation in general, and scientific documentation in particular, thanks to the CZI grant we received last year.

sphinx-hoverxref displaying a tooltip including an equation

Embedding content previews

Technical documentation is full of cross-references (or xrefs): hyperlinks to related parts of the documentation (or even to an external project) that help contextualize the information. Sphinx provides powerful tools for creating xrefs, which can be used to link other parts of the documentation, and in the case of software projects, also to specific objects of the API.

However, jumping through several links while reading some documentation can be distracting, since opening them might need either a context switch or keeping a new browser tab for a later moment.

Here is where sphinx-hoverxref comes to the rescue: it scans the cross-references and attaches content previews to them (either tooltips or modal dialogues) that embed the contents of the page the xrefs point to. This way, when the user is interested in a particular topic, they can hover the mouse over the link and display the content preview instead of opening the link.

Moreover, the content previews created by sphinx-hoverxref also work if the embedded content requires a particular extension to be rendered. This makes it possible to embed content that includes mathematical equations, for example.

Support for `intersphinx`

Version 0.6b1 of sphinx-hoverxref introduces opt-in support for Intersphinx linking. sphinx.ext.intersphinx is a Sphinx extension that generates automatic links to the documentation of objects in other projects, and now it’s possible to show floating windows on them too.

A project (left) embedding content from another project linked through intersphinx (right) using sphinx-hoverxref

To enable it, the user needs to specify which projects from the intersphinx_mapping will be scanned by sphinx-hoverxref, using a new configuration value:

# Values of the intersphinx_mapping keys that you want to enable hoverxref on
hoverxref_intersphinx = [
   "astropy",
   "numpy",
   "scipy",
   "matplotlib",
]

Moreover, the look & feel of the current project is preserved even if the target documentation has a different theme or colors, which makes the result more visually consistent.

Note

At the moment, the target project needs to be hosted on Read the Docs, which is a limitation that we hope to remove in the future.

You can draw inspiration from some community projects that are using this feature already:

The Grill, an extension for digital content creation with Maya, Houdini, and other 3D modeling applications, and references another project called naming.
poliastro, a Python library for interactive Astrodynamics that makes cross-references to Astropy and other projects.

We are excited to see what our users can do with sphinx-hoverxref, and will continue working on it in the future.

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!

Read the Docs Blog - Posts tagged czi-grant

New release of sphinx-hoverxref with support for intersphinx

Embedding content previews

Support for intersphinx

Support for `intersphinx`