bug: `signature_crossrefs` is creating unwanted links when instance attributes set using local variables

[hmellor]

Description of the bug

signature_crossrefs is creating links from local variables used to set instance attributes, where the docs say that it should only be doing it for type annotations.

This becomes a problem if the local variable name matches the name of a heading somewhere else in the docs.

To Reproduce

Setup:

pip install mkdocs-material mkdocs-api-autonav
touch mkdocs.yml
mkdir docs
touch docs/index.md
mkdir src
touch src/__init__.py

# mkdocs.yml
site_name: Docs
theme:
 name: material
plugins:
 - autorefs
 - mkdocstrings:
 handlers:
 python:
 options:
 show_if_no_docstring: true
 separate_signature: true
 signature_crossrefs: true
 - api-autonav:
 modules: ["src"]

<!-- docs/index.md -->
# Intro

# src/__init__.py
class Class:
 def __init__(self):
 intro = "Some text"
 self.attr = intro

Finally:

• run mkdocs serve
• open http://127.0.0.1:8000/reference/src/
• notice that:
  • intro has become a link
  • that link takes you to http://127.0.0.1:8000/#intro, which is unrelated

Expected behavior

This link should not have been created.

Environment information

• System: macOS-26.1-arm64-arm-64bit
• Python: cpython 3.12.8 (~/.venv/bin/python)
• Environment variables:
• Installed packages:
  • mkdocstrings-python v1.19.0

[pawamoy]

Thanks for the report @hmellor, I was able to reproduce the issue.

[pawamoy]

Not an easy one to fix! We'll probably have to keep track of locals declared in classes' __init__ methods, so that when trying to resolve a name, we see that it points to a local variable, meaning we shouldn't output a cross-reference.

[pawamoy]

For the explanation:

• we render a signature with cross-references enabled
• we see an ExprName(intro)
• we get its canonical path
• by resolving intro in its scope
• since it isn't found anywhere, we assume it's a builtin
• we therefore output an optional cross-ref
• turns out it matches the id of another heading in the site

So, as mentioned above, one solution is to keep track of locals in Python code to avoid outputing optional cross-refs that we know cannot be resolved (and worse, can wrongly be resolved to other irrelevant headings).

Another solution could be to return self.name as canonical path only when it's actually a built-in, with a hard-coded list. I avoided that in the past, because Python is dynamic and one could inject anything in __builtins__. But in the end, it's just about having the identifier in the known headings/ids, and something custom and injected wouldn't be documented as a builtin, but as a member of a third-party package. In short: even if intro was injected as a builtin (to be used globally), it wouldn't appear in Python's objects inventory anyway, so no point in trying to cross-ref it. So, I guess hard-coding builtins would work. That's still be a breaking change in our API, since canonical_path always return a string and now it would sometimes return None (probably?).