Unpin mkdocs-autorefs and fix multple URLs for warnings #1051
Conversation
This file contains 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
github-actions
bot
added
part:docs
github-actions
bot
added
the
part:tooling
llucax
added
the
cmd:skip-release-notes
llucax
force-pushed
the
fix-multiple-refs
branch
2 times, most recently
from
93fb407 to
1a1deca
Compare
|
Ready for review. |
This is in part to improve the docs but it was done also partially to solve the warning: "Multiple URLs found for ..." Probably just adding the new mkdocs options to the user-guide page would have been enough to remove the warning, but it still makes sense to move the high-level docs to the module anyway, so we keep that change too. Signed-off-by: Leandro Lucarella <[email protected]>
When multiple URLs were found for a autoref, the plugin emits a warning, which in our setup breaks the build as we use strict mode. This new option allows to resolve the reference to the "closest URL". See the documentation for more information: https://github.com/mkdocstrings/autorefs#non-unique-headings Signed-off-by: Leandro Lucarella <[email protected]>
Now that all warnings about "Multiple URLs for" were fixed, we can unpin `mkdocs-autorefs` and let it update to the latest version. Signed-off-by: Leandro Lucarella <[email protected]>
llucax
force-pushed
the
fix-multiple-refs
branch
from
1a1deca to
ded52da
Compare
matthias-wende-frequenz
approved these changes
Sep 2, 2024
shsms
approved these changes
Sep 2, 2024
|
|
||
| ### Composition | ||
| Example: Streaming the power of a battery pool. | ||
| ```python |
There was a problem hiding this comment.
You're already saying please refer to the module documentation, so why can't they get their examples from there too? It looks a bit weird to have examples after the line that tells people to go elsewhere.
Besides, the formula engine examples already take so long in CI. Now it is going to be twice as long. :-((
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 PR unpins the
mkdocs-autorefsplugin, so we can use the latest version, but to do that we need to make some changes to the way we link to sections in the docs.The new version produces warnings when there are more than one possible URL to resolve an "autoref" link, and since we have strict more enabled, the docs fail to build if we have any warnings.
The simplest way to avoid the warning in some cases is just adding the following options:
This avoids anchors being created in the user guide, so it removes the ambiguity of the link.
To remove some other warnings we add a new
autorefsplugin option toresolve_closest, which allows to resolve the reference to the "closest URL". See the documentation for more information: https://github.com/mkdocstrings/autorefs#non-unique-headings.This PR was done following suggestions in: