Enhance your code examples with links to reference docs

"Like the Sphinx" by Benson Kua is licensed with CC BY-SA 2.0.

Why is it not everywhere?

Some time ago when browsing Matplotlib's documentation, I was awestruck: I could click their code examples to get taken to the reference documentation of whatever class or function was used. What a great feature! It makes navigating documentation much easier.

So I tried to track down where those links were inserted. Turns out it was an extension called Sphinx-Gallery, which converts Python files to RST while capturing the script output. Awesome! But it didn't work for ordinary RST documentation, and it executes the code - two assumptions I didn't want to make with my own documentation. After searching around and slowly realising that it really did not exist, I set out to create a tool of my own! Enter sphinx-codeautolink.

What it does

As advertised, it matches code example contents to definitions documented elsewhere with Sphinx:

Clicking the link would take you to numpy.linspace's documentation. Other key features include:

• Backreference tables: a table of examples where a particular definition is used
• Autodoc integration: insert backreference tables to all definitions documented with autodoc
• Intersphinx integration: as seen in the image above, linking to docs of external libraries is super simple
• Python console example support (>>> prefixed code)
• Invisible imports, example concatenation, simple type hint resolving and more!

How to use it

Easy. I wanted to make it work out of the box for most documentation, so if your examples are valid Python you're most likely already there. I had to add some import statements to my examples. Other than that, it's only a matter of installing the package and adding it to the list of Sphinx extensions!

$ pip install sphinx-codeautolink

# conf.pyextensions = [    ...,    "sphinx_codeautolink",]

Our examples have a more comprehensive explanation of all the use cases and RST syntax.

How it works

The principle is quite simple: all code blocks are parsed and the names contained in them are traced back to definitions documented with Sphinx elsewhere in the documentation. Sphinx does its thing and after the HTML is written, links are injected to the correct places.

Naturally I made a few assumptions, some different than the folks at Sphinx-Gallery: it is only usable with HTML documentation and I had to cut some corners with the parsing implementation. I didn't aim to emulate the Python runtime, just provide a correct result for the 99 % case. None of the shortcomings should cause problems with reasonable example code. But Sphinx-Gallery does perform better in some situations. For example where we'd have to analyse complex type hints, Sphinx-Gallery can simply look at the variable's type.

I've poured my last month on this and really enjoyed the deep dive into Sphinx and docutils. I hope you'll get some use out of it!

Links

Documentation, PyPI, GitHub