René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"bug: relative cross-references in inherited members still depend on the consumer's `relative_crossrefs` setting","articleBody":"### Description of the bug\n\n#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](https://github.com/mkdocstrings/python/blob/c888dc294f4c8305479d358e976fd8cbb2e0c62c/src/mkdocstrings_handlers/python/_internal/rendering.py#L808), 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.\n\nThis 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.\n\n### To Reproduce\n\nThe reproducer in #341 still applies unchanged. With `mkdocstrings-python==2.0.9`, its case 2 (`pkgb` built without `relative_crossrefs`) fails exactly as before:\n\n```\n### 2. pkgb's docs, without relative_crossrefs: the raw dotted string leaks\nWARNING -  mkdocs_autorefs: index.md: from /path/to/repro/pkga/sub.py:10: (pkgb.Derived.MAPPING) Could not find cross-reference target '....Thing'\n\nAborted with 1 warnings in strict mode!\n```\n\nCase 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.\n\n### Full traceback\n\nNo traceback, only the `mkdocs_autorefs` warning above, which aborts the build in strict mode.\n\n### Expected behavior\n\nA 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.\n\n### Environment information\n\n- __System__: Linux-6.12.107+deb13-amd64-x86_64-with-glibc2.42\n- __Python__: cpython 3.12.14\n- __Environment variables__:\n- __Installed packages__:\n  - `mkdocs` v1.6.1\n  - `mkdocstrings` v1.0.6\n  - `mkdocstrings-python` v2.0.9\n  - `mkdocs-autorefs` v1.4.4\n  - `griffelib` v2.3.0\n\n### Additional context\n\nThis is the same real-world case described in #341. [frequenz-quantities](https://github.com/frequenz-floss/frequenz-quantities-python) 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](https://github.com/frequenz-floss/frequenz-sdk-python) subclasses `QuantitySchema` and builds its docs with `inherited_members: true` and `strict: true`, but [without `relative_crossrefs`](https://github.com/frequenz-floss/frequenz-sdk-python/blob/8616b9ac2a40a3c41f2a824aaa79e108e3edcf35/mkdocs.yml#L105-L116). 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`:\n\n```\nWARNING -  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'\n```\n\nWith `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.\n","author":{"url":"https://github.com/llucax","@type":"Person","name":"llucax"},"datePublished":"2026-09-24T07:55:31Z","url":"https://github.com/mkdocstrings/python/issues/345"}