sphinx-autocodelink

Automatically add links to code blocks in Sphinx documentation.

This extension is similar to sphinx-codeautolink, except it uses dynamic analysis to resolve links instead of static analysis. The dynamic analysis is based on how Sphinx-Gallery resolves links for its 'reference_url' configuration option.

Installation

pip install sphinx-autocodelink

Add the extension to your Sphinx conf.py:

extensions = [
    ...,
    'sphinx_autocodelink',
]

Usage

Links only appear on code you actually run through one of the two mechanisms below. Each is opt-in by use: nothing happens unless you write the directive, or add the scraper -- there's no conf.py switch to flip.

The autocodelink directive

Write it wherever you want a code block executed and linked. It only affects that one block:

.. autocodelink::

   import pkg
   pkg.thing()

No figure or other output is produced, just a syntax-highlighted, linked code block. Doctest-style content (>>>) also works, with prompts stripped before execution.

Sphinx-Gallery

Sphinx-Gallery already executes your example scripts; this hooks into that execution instead of running anything itself. Add AutoCodeLinkScraper alongside your real image scraper(s):

from sphinx_autocodelink.gallery import AutoCodeLinkScraper

sphinx_gallery_conf = {
    'image_scrapers': (AutoCodeLinkScraper(), ...),  # ... = your other scraper(s), if any
}

Sphinx-Gallery's own parallel=True mode runs each example in a separate worker process, bypassing Sphinx's usual mechanism for merging data back into the main build. AutoCodeLinkScraper writes its records to disk instead, so they survive regardless.

Drop any module from sphinx_gallery_conf['reference_url'] once you add AutoCodeLinkScraper for it. reference_url is Sphinx-Gallery's own, older code-linking mechanism, and it isn't aware of this extension: both wrap the same <span> code identifiers, and Sphinx-Gallery's own embedder doesn't check whether a match is already inside a link. Leaving reference_url configured for the same module produces broken, nested <a> tags:

<a class="sphinx-autocodelink-a" href="..."><a href="..." class="sphx-glr-backref-...">...

Use intersphinx_mapping instead, which this extension already reads -- it covers every page, not just gallery pages, and Sphinx-Gallery's own reference_url = None (local resolution) is redundant with it anyway.

Backreferences index

.. autocodelink-index:: lists every linked name and the pages that reference it, filled in once the whole site's links are known:

.. autocodelink-index::

Pass a documented dotted name to show just its own references -- handy on that name's own API page:

.. autocodelink-index:: pkg.thing

Library use

A consumer that already executes example code for its own purposes (e.g. to render a figure) can skip the directive and AutoCodeLinkScraper entirely, and call record_namespace() directly with the resulting namespace. For example, pyvista's pyvista-plot directive already builds its own namespace via exec(code, ns) to render a figure; adding autolinking is one extra call after that:

from sphinx_autocodelink import record_namespace

record_namespace(env=env, docname=env.docname, source=code, namespace=ns)

Then, from the consumer's own setup(app), call app.setup_extension('sphinx_autocodelink'):

def setup(app):
    app.setup_extension('sphinx_autocodelink')
    app.add_directive('pyvista-plot', PlotDirective)
    ...

Development

uv sync --group dev
uv run pytest
uv run pre-commit run --all-files