fix: Expand relative cross-references against the object the docstring was written on - #342
Open
devtechedge wants to merge 1 commit into
Open
Conversation
…g was written on With inherited members enabled, docstrings of base class members are rendered in the docs of the inheriting class, where the current object is a Griffe alias living under the inheriting class. Leading-dot relative cross-references found in such docstrings were therefore expanded against the consumer's tree instead of the dependency's tree, resolving to wrong targets or failing strict builds. Anchor the dot-walk on the docstring's parent (the defining object) when it is reachable, falling back to the current object otherwise.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
With
inherited_membersenabled, the docstring of a base class member is rendered in the docs of the inheriting class. InAutorefsHook.expand_identifier, leading-dot relative cross-references found in such docstrings walk up fromcurrent_object, which for an inherited member is a Griffe alias living under the inheriting class. A reference written onpkga.sub.Base.MAPPINGtherefore expands topkgb.Thingin the docs of a package that subclassesBase, instead ofpkga.Thing, silently linking to a wrong target or aborting strict builds when the consumer hasrelative_crossrefsdisabled.This change anchors the dot-walk on the docstring's parent, the object the docstring was actually written on, when that object is reachable, and falls back to the current object otherwise. This mirrors how
get_contextalready usesdocstring.parentfor source location. The reproducer and root-cause analysis in #341 describe exactly this behavior, including the frequenz-sdk build failure against frequenz-quantities.A regression test in
tests/test_rendering.pybuilds two in-memory modules with cross-module inheritance and asserts a....Thingreference in an inherited member's docstring expands topkga.Thing; it fails on main and passes with this change. A control assertion also checks that non-inherited objects still expand identically.Re-export aliases are anchored uniformly by this change: since
docstring.parentof a re-export alias points at the private defining object, relative references there now expand against it. If different treatment is preferred for re-exports, happy to follow maintainer guidance. Whether the consumer'srelative_crossrefssetting should gate expansion of a dependency's docstring at all is out of scope for this PR.Fixes #341