👌 Handle external references pointing to object types #12133
Merged
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
chrisjsewell
changed the title
picnixz
requested changes
Mar 19, 2024
Co-authored-by: Bénédikt Tran <[email protected]>
picnixz
reviewed
Mar 19, 2024
picnixz
reviewed
Mar 19, 2024
Co-authored-by: Bénédikt Tran <[email protected]>
picnixz
approved these changes
Mar 19, 2024
Co-authored-by: Bénédikt Tran <[email protected]>
chrisjsewell
added a commit
that referenced
this pull request
Mar 25, 2024
The key issue this commit seeks to address, is that existing tools / documentation often lead users to mistakenly use object types and not role names, a classic example being `function` not `func` Previously, the warning message for using e.g. `` external:function`target` `` (with `py` as the default domain), would be: ``` WARNING: role for external cross-reference not found: function ``` This gives no information to the user on how to fix the issue, even though there is actually quite an easy fix This commit adds logic to create more specific / helpful warning messages, e.g. ``` WARNING: role for external cross-reference not found in domains 'py', 'std': 'function' (perhaps you meant one of: 'py:func', 'py:obj') ``` This goes through the same original logic but, if the role is not found, it will look if the role name is actually an available object type on the domain(s), and then suggest its related roles. This commit also reverts #12133, which provided a (silent) fallback to auto convert an object type to a role name.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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 fixes the issue of
objects.invdenoting object names, whilst theexternalrole only allows for role names.As an example, take the
objects.invfor the sphinx documentation, which contains:A user might understandably expect that they could reference this using
:external:py:function:`compile`, but actually this would currently error with:this is because,
functionis the object type, yetexternalexpects the related role namefunc😒It should not be necessary for the user to know about this distinction, and in fact all the documentation talks about object types, not role names: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#explicitly-reference-external-objects
In this PR, we add logic, to first look if the name relates to a role name (as previously, to not be back-breaking) but, if not, then also look if the name relates to an object that has a known role and, if so, use that.