Repository navigation
Use absolute cross-references in docstrings - #207
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 3 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. 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 exactly the same links as before, with both mkdocstrings-python 2.0.7 and 2.0.9. 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 when it didn't fit. 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>
github-actions
Bot
added
part:tooling
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 floated to the new version and every docs build now
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>
llucax
marked this pull request as ready for review
October 23, 2026 08:49
llucax
requested review from
Marenz and
daniel-zullo-frequenz
and
a balanced review from Copilot
and removed request for
a team
October 23, 2026 08:49
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes are limited to documentation and its tooling, with valid public reference targets and no unresolved blocking issues.
No open issues 🎉
What changed in this PR
This PR makes the library’s docstring links independent of relative-reference handling, preparing the documentation for the mkdocstrings-python update in #204. Runtime behavior and public APIs are unchanged.
Changes:
- Replace relative docstring cross-references with absolute public API paths.
- Remove
relative_crossrefs: trueand bump mkdocstrings to 1.0.7 for build compatibility. - Document the cross-reference fix in the release notes.
| File | Description |
|---|---|
src/frequenz/core/warnings/_ignoring.py |
Use absolute links to warning-suppression utilities. |
src/frequenz/core/warnings/_deprecated_aliases.py |
Use absolute links to alias utilities and attributes. |
src/frequenz/core/warnings/_asserting.py |
Use absolute links to warning assertion and suppression utilities. |
src/frequenz/core/warnings/__init__.py |
Update module documentation links to public paths. |
src/frequenz/core/math.py |
Update type-variable and interval attribute links. |
src/frequenz/core/enum.py |
Update enum utility links and clarify a constructor docstring. |
RELEASE_NOTES.md |
Explain the documentation compatibility fix. |
pyproject.toml |
Bump mkdocstrings from 1.0.6 to 1.0.7. |
mkdocs.yml |
Remove relative cross-reference handling. |
Review effort: Balanced
Marenz
approved these changes
Oct 23, 2026
Marenz
left a comment
Marenz
left a comment
Contributor
There was a problem hiding this comment.
🤖 LGTM. Checked that no relative cross-reference (][.…]) is left in src/, and the docs build runs with strict: true, so a broken absolute target would fail CI.
This was referenced Oct 23, 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.It unblocks #204: the docs build with mkdocstrings-python 2.0.9 now passes.
It also bumps mkdocstrings to 1.0.7, since pymdown-extensions 12.2 broke the docs build with 1.0.6 (mkdocstrings/mkdocstrings#829).