Repository navigation
Use absolute cross-references in docstrings - #566
Merged
Merged
Conversation
Since mkdocstrings-python 2.0.9, relative cross-references are expanded from the path where an object is defined, not where it is documented. All our public symbols are defined in private modules and re-exported from a public package, so 28 of the current references can't be found anymore and the strict documentation build fails, blocking the bump. Counting the dots from the private module would fix the build, but it ties the references to the private module layout, breaks them on older mkdocstrings-python versions, and can make references to inherited members silently link to the wrong class (`Receiver.ready()` would link to `BroadcastReceiver.receive`, for example). Relative references are also hard to read in an IDE, and only work in projects rendering our inherited docstrings if they enable `relative_crossrefs` too. All relative references are converted to absolute references to the public path of their target, which don't depend on any of that. The built documentation has the same links as before, with both mkdocstrings-python 2.0.7 and 2.0.9, except for the few that moved because of a reworded summary. Some paragraphs are rewrapped to fit the longer references, and a few summaries that got too long are reworded, moving the reference to the body. References in docstrings of private classes, which are not rendered, now point to the public symbol they were meant for, like the `Receiver` method being overridden. See frequenz-floss/frequenz-repo-config-python#655 for details. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
No docstring uses relative cross-references anymore, so the option is removed to stop new ones from being added. Absolute references to public paths are the convention from now on. See frequenz-floss/frequenz-repo-config-python#655 for details. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
pymdown-extensions 12.2 added a required `md` argument to
`pymdownx.highlight.Highlight.__init__()`, which mkdocstrings 1.0.6
subclasses without passing it. pymdown-extensions is only a transitive
dependency, so it floats to the new version and the docs build fails
with:
TypeError: Highlight.__init__() missing 1 required positional argument: 'md'
mkdocstrings 1.0.7 passes `md` when the parent accepts it
(mkdocstrings/mkdocstrings#829). 1.0.8 is out too, but it changes the
code anchor IDs, so it is left for its own bump.
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
github-actions
Bot
added
part:tooling
llucax
marked this pull request as ready for review
October 23, 2026 13:04
llucax
requested review from
florian-wagner-frequenz
and removed request for
a team
October 23, 2026 13:04
llucax
enabled auto-merge
October 23, 2026 13:12
daniel-zullo-frequenz
approved these changes
Oct 26, 2026
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.
This converts every relative cross-reference in the docstrings to an absolute reference to the target's public path, and removes
relative_crossrefs: truefrommkdocs.yml, as proposed in frequenz-floss/frequenz-repo-config-python#655.Some links silently changed target (
Receiver.ready()linking toBroadcastReceiver.receive, for example). Now it builds cleanly.It also bumps mkdocstrings to 1.0.7, since pymdown-extensions 12.2 broke the docs build with 1.0.6 (mkdocstrings/mkdocstrings#829).