intersphinx.external usage and documentation questions

[jdillard]

I recently discovered the intersphinx.external warning type for suppress_warnings through #12585 (comment), but it is unclear to me all the types of warnings intersphinx.external applies to. The test_intersphinx_role test does seem to hint at some possibilities.

I was hoping to use intersphinx.external to suppress warnings where a reference isn't found in an external inventory, but that doesn't seem to be supported in my testing. So my question is, is it possible to use intersphinx.external to suppress warnings where a reference isn't found in an external inventory?

---

Also, in doing research, I was reading about the new(er) intersphinx syntax in the sphinx.ext.intersphinx docs and noticed a potential error on L81. It has a typo with a missing leading colon, but also the syntax doesn't match the syntax in the external role docs, making the proper syntax:

:external+python:ref:`comparison manual <comparisons>`

I'm happy to make a PR to fix the typo, but didn't know if more (small, as I know there is a lot of sweeping improvements to be made) docs updates would come out of a potential discussion.

edit: PR made: #12941

[jdillard]

Ahhh, I should be using ref.ref, ref.doc, etc. I'll leave this up if anyone has additional docs improvement suggestions, otherwise I'll give it some thought and try based on my attempt at using suppress_warnings for such things.

[jayaddison]

Hey @jdillard - I noticed your documentation fixup pull request related to this, thanks!

I didn't quite understand what you mean by using ref.ref / etc instead, though - what do those affect?

[jdillard]

I'm away from my computer so don't have links to code handy, but essentially when the interspinx extension handles reference warnings it assigns the type.subtype as ref.ref, ref.doc, etc. So that means you need to use those to suppress warnings. I personally think it would be better if the type.subtype was something like ref.external+ref, ref.external+doc, etc for external references so there was more granular control of warning suppression.