importlib documentation doesn't declare functions properly

[ncoghlan]

https://docs.python.org/3/library/importlib.metadata.html#distribution-versions doesn't actually define a Sphinx function for version, so attempted references with `:func:`importlib.metadata.version` (including via the intersphinx extension) fail.

Edit: fixed the backticks thanks to @serhiy-storchaka's tip below (TIL that you can use repeated backticks with trailing and leading space for inline code markup, allowing inclusion of single backticks in the quoted code)

Linked PRs

• gh-125018: Add importlib.metadata semantic link targets #125027
• [3.13] gh-125018: Add importlib.metadata semantic link targets (GH-125027) #125047
• [3.12] gh-125018: Add importlib.metadata semantic link targets (GH-125027) #125048
• gh-125018: Fix role syntax #125050
• [3.12] gh-125018: Fix role syntax (GH-125050) #125055
• [3.13] gh-125018: Fix role syntax (GH-125050) #125080

[serhiy-storchaka]

Use triple backticks :func:`importlib.metadata.version`.

[webknjaz]

@serhiy-storchaka nope, @ncoghlan is right. For the full list of exposed objects, I have this little helper that updates every several hours: https://webknjaz.github.io/intersphinx-untangled/docs.python.org/.

And the terminal way to see what's exposed would be python -Im sphinx.ext.intersphinx https://docs.python.org/en/3/objects.inv.

These references don't come from Python runtime but from Sphinx. They must be properly declared in Sphinx in order to be linkable.

Single backticks work depending on Sphinx config. In that case, it's because of default_role = 'any' that Sphinx attempts finding any object of any role matching the name in intersphinx (and the site-local domain).

[serhiy-storchaka]

I meant that you can use triple quotes to quote text containing single or double backquotes in Markdown.

[ncoghlan]

I fixed the initial post to avoid requiring imagination of the actual reference syntax (thanks to @serhiy-storchaka's tip, I learned something new about Markdown today: https://meta.stackexchange.com/questions/82718/how-do-i-escape-a-backtick-within-in-line-code-in-markdown ).

[ncoghlan]

Posted a PR that adds the minimal text needed to define valid semantic cross-reference targets. The phrase "as described below" features heavily in their descriptive text, since I didn't want to embark on a wholesale rewrite of the module docs just to fix a cross-referencing issue.

[webknjaz]

I fixed the initial post to avoid requiring imagination of the actual reference syntax (thanks to @serhiy-storchaka's tip, I learned something new about Markdown today: meta.stackexchange.com/questions/82718/how-do-i-escape-a-backtick-within-in-line-code-in-markdown ).

One stray backtick still renders for me, though..

[ncoghlan]

Thanks for the syntax cleanups @AA-Turner (I incorrectly assumed that Sphinx would error on the !~ syntax if it didn't understand it, missing the possibility that it might just treat everything after the ! as a plain text string to pass through to the rendered output, which is what actually happened).