Repository navigation
Use absolute cross-references in docstrings - #295
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 the strict documentation build fails with 330 warnings, 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 targets were taken from what mkdocstrings-python 2.0.7 expanded each reference to, and apart from the reworded summaries mentioned below, the built documentation has the same links as before, with both mkdocstrings-python 2.0.7 and 2.0.9. The only exception are the 3 references in `ElectricalComponent` and `BaseElectricalComponentConnection` documenting inherited members, which used to link to the copy of the member in each subclass and now link to the member in the base class, where it is defined. A few references in docstrings that are not rendered (private attributes and a test) are converted too, using the target they were meant to point to. Paragraphs are rewrapped to fit the longer references, and the summaries that got too long are reworded, moving the reference to the body or leaving it to the `Args` or `Returns` section, which already had it in most cases. 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 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>
github-actions
Bot
added
part:docs
llucax
marked this pull request as ready for review
October 23, 2026 12:56
llucax
requested review from
daniel-zullo-frequenz
and removed request for
a team
October 23, 2026 12:56
llucax
enabled auto-merge
October 23, 2026 12:56
daniel-zullo-frequenz
approved these changes
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 also bumps mkdocstrings to 1.0.7, since pymdown-extensions 12.2 broke the docs build with 1.0.6 (mkdocstrings/mkdocstrings#829).