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.

Limitation: only resolves identifiers in an example's own top-level (module) scope. A root identifier that only ever exists inside one of the example's own helper functions -- a local variable, a parameter -- isn't resolvable:

def plot_it(mesh):
    smoothed = mesh.smooth_taubin()  # not linked: `smoothed` never leaves plot_it's own scope
    smoothed.plot()


plot_it(pv.Sphere())

There's no workaround for Sphinx-Gallery examples specifically -- this is different from the standalone .. autocodelink:: directive and record_namespace(), which do resolve this case (see Resolving identifiers local to a helper function); that mechanism traces the code's own execution, which isn't available to hook into Sphinx-Gallery's own execution of an example script.

A local name that's also bound at module level, to a value of the same type, resolves anyway -- resolution matches identifier text against the module namespace by name, not by real lexical scope, so a same-named module-level variable is indistinguishable from the local one shadowing it. Not a workaround to rely on deliberately: a same-named module-level variable of a different type resolves to the wrong link, not to no link at all.

If sphinx_gallery_conf['reference_url'] is also configured for a module AutoCodeLinkScraper covers too, both will try to link the same identifiers. This extension runs its own embedding after Sphinx-Gallery's, and skips anything already inside a link -- so the two don't produce broken, nested <a> tags, but Sphinx-Gallery's own (usually less precise, since it's static analysis rather than the real executed object) link wins wherever both would apply. Prefer intersphinx_mapping over reference_url, which this extension already reads and which covers every page, not just gallery pages -- then there's nothing to fall back to it for.

Bare doctest blocks (opt-in, site-wide)

The directive, the Sphinx-Gallery scraper, and library use (below) are all opt-in by use: only the specific blocks that name them get executed. autocodelink_autodoc_backrefs is the one exception -- set it and every bare >>> doctest block anywhere in the docs (a docstring's Examples section, a hand-written page, anywhere) is executed and its identifiers recorded, with no .. autocodelink:: needed on any of them individually:

autocodelink_doctest_blocks = True

Read this before enabling it:

• It runs code the page's author never marked as runnable, purely because it looks like a doctest session -- including in third-party docstrings pulled in via autodoc from dependencies you may not have fully read.
• A failing block doesn't fail the build, but it still ran first. A block that fails to parse or raises while running (elided/pseudo-code, one needing a resource that isn't there at build time) is skipped with a build warning -- but whatever it did before failing already happened.
• Each block gets its own fresh namespace. A later block can't see a name bound by an earlier one, even within the same docstring's Examples section -- unlike .. autocodelink::, which executes its whole content as one script.

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

Add :label: to wrap the list in a real section with that title, instead of rendering inline -- important if anything in your setup (e.g. an "on this page" sidebar built from real headings) needs a genuine section rather than inline content. Add :hide-empty: to omit the whole section, title included, when there's nothing to show, instead of printing "No references found.":

.. autocodelink-index:: pkg.thing
   :label: Used In
   :hide-empty:

Referencing pages show their real title by default (read straight from Sphinx's own tracked document titles), not their docname. Add :no-titles: to show docnames instead.

Set autocodelink_autodoc_backrefs = True to append exactly that -- a hidden-if-empty "Used In" section -- to every autodoc-documented object's own docstring automatically, via autodoc-process-docstring. Off by default; requires sphinx.ext.autodoc (directly, or via something that depends on it, e.g. numpydoc).

Grouping by category. AutoCodeLinkScraper tags every page it records 'Sphinx Gallery' by default (pass category= to change or clear it); .. autocodelink:: and record_namespace() take an optional category=/:category: of your own choosing. .. autocodelink-index:: uses this to group referencing pages -- but only adaptively: :group: auto (the default) groups by category only when a given entry's references actually span more than one category, otherwise it's today's flat list either way, so a name referenced from just one place never gets a pointless one-item subheading. Force it with :group: always or :group: never. Untagged pages fall under a generic 'Documentation' bucket whenever grouping does happen -- unless the recording happens from inside an object's own description (e.g. a docstring's Examples section, rendered through autodoc or a domain directive like .. py:function::), in which case it's tagged 'Docstring Examples' instead. Detected automatically when record_namespace()/.. autocodelink:: are given the calling directive's own state; not available to AutoCodeLinkScraper, since Sphinx-Gallery examples don't run inside any object's own description in the first place.

Set autocodelink_category_labels to rename categories' displayed group headings, without changing the category strings themselves (what :group: actually groups by) -- e.g. to drop implementation detail your readers don't need ("Sphinx Gallery" is a mechanism, not something a reader needs to know about):

autocodelink_category_labels = {
    'Sphinx Gallery': 'Gallery Examples',
    'Documentation': 'API Reference',
}

Long lists. Each rendered list (a whole flat list, or one category's group) shows at most 8 entries; past that it shows the first 5 and tucks the rest behind a <details> "N more" toggle, so a heavily-used name's index entry doesn't turn into a wall of links.

Styling. A 'Docstring Examples' entry links to another documented object's own page, so it renders like a real :class:/:func:/etc. cross-reference would (most themes style that bold, in a distinct color from a plain page link) -- the theme is doing that on its own, from the same docutils literal/xref markup a real cross-reference carries; nothing to configure here. An entry in any other category (a gallery example, a guide) is a genuine page link and stays plain.

Resolving identifiers local to a helper function

Only a script's top-level namespace is resolvable by default -- a root identifier that only ever exists inside one of the script's own helper functions (a local variable, a parameter) has nothing to look it up against, even though the code accessing it is right there. Use exec_with_local_scopes() in place of a plain exec() to also resolve those:

from sphinx_autocodelink import exec_with_local_scopes

namespace = exec_with_local_scopes(compile(code, filename, 'exec'), {}, filename)

It runs code exactly as exec(code, namespace) would, and returns a namespace with every one of the script's own function calls' own locals merged in underneath -- at the cost of some precision, a local name in one call can shadow what globals (or a different call) bound under the same name. Only frames compiled from filename are captured, so calls into library internals aren't traced or merged in.

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. Passing the directive's own state (see "Grouping by category" above) picks up the 'Docstring Examples' category automatically, when the consumer's own directive is itself used inside an object's own description:

from sphinx_autocodelink import record_namespace

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

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