Introducing sphinx-codeautolink: make your code examples clickable

[Felix Hildén]

Hi! As this is as close to a documentation SIG as it gets, I thought you might be interested to hear about an extension I've been developing for the last few months. sphinx-codeautolink inserts links to reference documentation for the functions and classes that a code example uses, making statements in the example clickable for easy navigation.

Have a look at a live demo on our documentation if you're interested:

https://sphinx-codeautolink.readthedocs.io

I've aimed for a minimal setup (only activating the extension) assuming your examples are already valid Python and you're using autodoc to document your library. But there are various knobs for hiding imports, concatenating examples, and an intersphinx integration to name a few advanced features. The extension supports python, pycon, doctest (also ext.doctest) and any complying third-party code blocks out of the box. It is also possible to add handlers for custom block types like IPython quite easily. Our parser supports full Python syntax, with some small caveats due to us not actually running any code, and even imports from your library to return type hints and superclasses.

I think it only makes documentation better. What do you reckon? I was inspired by the awesome docs of Matplotlib and Sklearn, which use Sphinx-Gallery to generate example galleries that are similarly linked, but sadly Gallery doesn't handle rST and always executes scripts.

Give it a spin and let me know what you think! If you run into any issues, I'd be happy to respond on our issue tracker.

Cheers!

Felix Hildén