In Sphinx 4.4 a new external role was added for use with the intersphinx references, which changes
the syntax of intersphinx references. The old format of a basic reference was:
:ref:`invname:target`
And the new format is:
:external+invname:ref:`target`
As covered in the intersphinx docs, using this new role forces the reference lookup to external projects only. This is in comparison to the previous behavior where Sphinx would look through all internal references before attempting to find external references, sometimes creating issues in the process.
Reasoning behind the change
@jakobandersen, the author of the changes, explains the main reasoning behind the change in this comment:
The external role was introduced because of problems with the extended [old] syntax, so I suggest to never use the extended syntax, but switch to the “external” role.
The main problem with the extended [old] syntax is that each domain (
py,c,cpp,js, etc.) needs to support it, but using a:as delimiter is making it very complicated to do so in a clean way. […] It was part of a larger overhaul of intersphinx to support domains in a generic manner.
So if you don’t use domains in your Sphinx projects, you may not run into any issues keeping or continuing to use the old “extended” syntax, but there are benefits to switching over to the new syntax.
Switching over to the new syntax
To make it easier to switch to the new syntax use a couple find and replace regexes, one for when a title is specified and one where it isn’t. These can be used in VS Code’s Replace in Files with the regex option selected.
Here is the find/replace pair for external references without a title (test on regex101):
// find regex for external references without a title
:(ref|doc|term):`([^<`:]+):([^:]+)`
// replace with
:external+$2:$1:`$3`
And the find/replace pair for external references with titles (test on regex101):
// find regex for references with a title
:(ref|doc|term):`([^`]+)\s?<([^:`]+):([^:`]+)>`
// replace with
:external+$3:$1:`$2 <$4>`
Make sure to verify the changes with git diff.
