`:std:event:` role is mentioned in the intersphinx database but not exposed in Sphinx runtime

[webknjaz]

Describe the bug

The HTML-table version of the Sphinx's own objects.inv can be found at: https://webknjaz.github.io/intersphinx-untangled/www.sphinx-doc.org/

As you can see, there is this section for "std:event" suggesting that the exposed identifiers are usable with this role but they are not.

Sphinx says that it's an unknown interpreted role:

......py:docstring of sphinxcontrib.towncrier.TowncrierDraftEntriesEnvironmentCollector:12: WARNING: Unknown interpreted text role "std:event".

But how does this work in Sphinx's own docs, then?

I tried to do some digging and it is hard to figure out why this works but my archaeological attempts lead me to https://github.com/sphinx-doc/sphinx/blob/f7768d8/doc/conf.py#L163-L166 which is probably how this is implemented (and it would explain why pip installed sphinx knows nothing about :event:).

To Reproduce

Add

extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {
    'python': ('https://www.sphinx-doc.org/en/master', None),
}
nitpicky = True

to conf.py.

And add something like

:event:`env-get-outdated`

to index.rst.

Building this with

$ rm -rf _build; python -m sphinx -W --keep-going -a . _build

will cause warnings saying WARNING: Unknown interpreted text role "std:event".

Expected behavior

It should be possible to add https://www.sphinx-doc.org/en/master to intersphinx_mapping to conf.py and then use the :event: role to point to Sphinx's docs.

Your project

N/A

Screenshots

N/A

Environment info

• OS: Gentoo Linux (seems irrelevant, though)
• Python version: 3.9.0
• Sphinx version: 3.x
• Sphinx extensions: sphinx.ext.intersphinx
• Extra tools: N/A

Additional context

• This seems to have been added in 2b0e015#diff-e170e9a7d787c21095c6c11bb25f0f1ff0294a42a46d45ba6fb5ed794e457624R186

[tk0miya]

It's a custom object type of Sphinx document. Please check our conf.py.
https://github.com/sphinx-doc/sphinx/blob/3.x/doc/conf.py#L165-L166

I suppose you can refer to the event if your project also adds it. Could you try it?

[webknjaz]

Yes, that works but this should probably be fixed in Sphinx itself.

[tk0miya]

What do you mean? It's a custom object type of Sphinx itself. So it should not be bundled to the core, I think.

[webknjaz]

Why not? I think everything linkable via intersphinx should be exposed. Or maybe put it under the Sphinx domain like :sphinx:event:...
Alternatively, maybe intersphinx could be extended to automatically detect any roles present in objects.inv and inject them into the runtime where it's used.

[tk0miya]

I can understand your goal is providing a way to event of Sphinx docs. +0 to create sphinx domain (as sphinxcontrib module) if somebody helps. But I don't have an answer if your goal is exposing all of linkable items in the inventory. It's very complicated and hard to implement.

[webknjaz]

What is complicated exactly? Doesn't intersphinx format provide all the necessary information for generating things on fly?

[tk0miya]

Now we're discussing the new format of the inventory format. We've felt it's incomplete to look up objects correctly (see #8929), and domain support is needed to look up them. Additionally, some roles have their original features (adding parenthesis, cut-off names, and so on). I think it's difficult to generate from inventory automatically.