bug: relative cross-references in inherited members still depend on the consumer's `relative_crossrefs` setting

[llucax]

Description of the bug

#342 (released in 2.0.9) fixed half of #341: relative cross-references in inherited members now expand against the object the docstring was written on, instead of the inheriting class. The other half is still there. The expansion is still gated on the consumer's own relative_crossrefs setting, so when a package without that option renders an inherited member whose docstring comes from a dependency that uses relative cross-references, the raw dotted identifier is still handed to autorefs and a strict build fails. #342 left this out of scope explicitly, but #341 was closed as fixed, so I'm opening this to keep track of it.

This means the consumer's configuration still decides whether a dependency's docstrings resolve. A library author can't tell whether all their downstream users enabled relative_crossrefs, and a downstream user shouldn't have to adopt a docstring style just because a base class they inherit from uses it.

To Reproduce

The reproducer in #341 still applies unchanged. With mkdocstrings-python==2.0.9, its case 2 (pkgb built without relative_crossrefs) fails exactly as before:

### 2. pkgb's docs, without relative_crossrefs: the raw dotted string leaks
WARNING -  mkdocs_autorefs: index.md: from /path/to/repro/pkga/sub.py:10: (pkgb.Derived.MAPPING) Could not find cross-reference target '....Thing'

Aborted with 1 warnings in strict mode!

Case 3 now expands to pkga.Thing, which is correct. In that toy setup it still fails in strict mode, but only because docs-b neither renders pkga nor loads an inventory for it, so that part is expected and not a bug.

Full traceback

No traceback, only the mkdocs_autorefs warning above, which aborts the build in strict mode.

Expected behavior

A leading-dot identifier written in a docstring should be expanded whether or not the package rendering it enabled relative_crossrefs, at least when the docstring was written on an object other than the one being rendered (as is the case for inherited members). As far as I can tell, an identifier starting with a dot can never resolve as an absolute one, so expanding it wouldn't break any reference that works today.

Environment information

• System: Linux-6.12.107+deb13-amd64-x86_64-with-glibc2.42
• Python: cpython 3.12.14
• Environment variables:
• Installed packages:
  • mkdocs v1.6.1
  • mkdocstrings v1.0.6
  • mkdocstrings-python v2.0.9
  • mkdocs-autorefs v1.4.4
  • griffelib v2.3.0

Additional context

This is the same real-world case described in #341. frequenz-quantities had to turn the relative cross-references in frequenz.quantities.experimental.marshmallow into absolute ones (frequenz-floss/frequenz-quantities-python#170), because frequenz-sdk-python subclasses QuantitySchema and builds its docs with inherited_members: true and strict: true, but without relative_crossrefs. With 2.0.9 we wanted to restore the relative references, but after reverting that change locally, the SDK docs still fail with 2.0.9 unless the SDK also enables relative_crossrefs:

WARNING -  mkdocs_autorefs: reference/frequenz/sdk/config/index.md: from .../frequenz/quantities/experimental/marshmallow.py:330: (frequenz.sdk.config.BaseConfigSchema.TYPE_MAPPING) Could not find cross-reference target '.....Quantity'

With relative_crossrefs: true in the SDK, 2.0.9 builds cleanly and links to frequenz.quantities.Quantity through the quantities inventory, so the #342 fix itself works as intended.

[pawamoy]

Thanks, I missed the second half. Then I guess we could decide to always enable relative crossrefs since they don't cause any issues. However since there's an easy solution (explicitly adding relative_crossrefs: true to your setup) and mkdocstrings-python is in maintenance mode, I'm inclined not to change anything here.

[llucax]

Yeah, the problem is a change in a upstream project can potentially break all downstream projects (although in very particular cases only, which does makes it an obscure bug). I agree with the sentiment of being too niche to worth fixing in a project soon to be phased out. How does this work with Zensical, I thought the handlers implementation for mkdocstrings was shared, because mkdocstrings is already supported in Zensical, right? Does this bug still applies there?

[pawamoy]

We try to mirror MkDocs as much as possible, so yes, the behavior is the same there. I hear the argument that an upstream project can break downstream ones by starting to use relative cross-refs 🤔

The thing is we're also subject to this issue with scoped_crossrefs. And currently scoped_crossrefs is not safe to enable by default, because it (wrongly) gives precedence to local names rather than absolute ones when there's a match. Fixing this precedence requires changes in autorefs and mkdocstrings-python. So either we fix it in both mkdocs-autorefs + mkdocstrings-python and Zensical, or we just defer that to our improved API docs work (including a cross-reference system) in Zensical.

Yeah I'm gonna go with the second option for now, as I'd prefer avoiding changes in mkdocs-autorefs. I hope you can understand 🙏