intersphinx: Allow strict prefix matching

[nijel]

Subject: Add optional strict prefix matching to intersphinx

Feature or Bugfix

• Feature

Purpose

• allows better control on what links go to the external documentation

Detail

Strictly using prefix for intersphinx links gives a better control on
external links - only links explicitely declared will point to the
external documentation.

Fixes #2068

Relates

• Add an option to not use intersphinx references as a fallback #2068

[tk0miya]

LGTM with nits.

[tk0miya]

Is this initialization needed? I think the configuration is initialized as False by default. So this assignment is not needed. I understand setting it up explicitly in test_missing_reference. But I don't understand why are they added in other cases.

[nijel]

I didn't work without that. Unfortunately, I have no clue how this works in the tests...

[jakobandersen]

Hmm, I'm not sure this is a descriptive name for the feature. How about something like intersphinx_resolve_only_explicit?
But even then, this doesn't seem like the right way to go. As argued in #8418, it seems strange to me to ask a domain to resolve a reference that you don't actually want it to resolve, just so intersphinx can pick it up.
I suggest a more direct apporach with an intersphinx role for requesting an intersphinx resolution, and then more fine-grained config vars to disable the missing-reference event handler.

[nijel]

As for name, I'm open to change it to anything. Changing intersphinx massively is something I can't do.

Having a dedicated role for intersphinx as you describe #8418 (comment) and having a way to disable handling of missing references would work for us as well. The drawback of this approach might be that it would require new Sphinx to build, while changing way the lookups works as done in this PR would keep the documentation compatible with current Sphinx as well (only the strict lookup would not be performed, what is fine as long as we do the validation in CI using compatible version).

I want to explicitly define where interphinx should be used and let Sphinx fail on missing references instead of silently picking up a reference from random linked documentation which happens to have a target which we forgot to define.

[phlax]

it would be incredibly useful to have this feature added.

without it intersphinx is basically unusable for versioning

[phlax]

@nijel do you still need this ? Any chance of rebasing/updating to resolve conflicts ?

if not, i could possibly take on this PR as it would be helpful to us to have this landed upstream

[nijel]

I've just rebased it...

[jakobandersen]

In connection with some of the other recent intersphinx discussions I think a single config var is too limiting. For example, one may like to disable intersphinx lookup for roles like :ref: and :doc:, but keep it for all xref generated by source code constructs, e.g., all directives in the Python, C, C++, Javascript, RST, etc. domains.
Perhaps it should be a list of disallowed domains, which defaults to [] by in sphinx-quickstart gets set to ['std']? I guess this is the domain that gives the most surprising lookups?

[phlax]

disable intersphinx lookup for roles like :ref: and :doc:, but keep it for all xref generated by source code constructs...a list of disallowed domains, which defaults to []

this sounds useful but my feeling is that it adds 2 layers of complexity

just being able to disable the lookup up for non explicitly tagged links is incredibly useful if you want to use intersphinx with different versions of the same docs (we are using @nijel 's patch and its working v well)

how about we land this and then i would potentially be up for contributing further in terms of adding more fine-grained controls over intersphinx lookups

[jakobandersen]

See #9459 for an implementation of #8981 (comment).

[jakobandersen]

Replaced by #9459, specifically by setting intersphinx_disabled_reftypes = ['*']. Though intersphinx_disabled_reftypes = ['std:doc'] should be enough to fix most silent resolution problems.