Repository navigation
importlib documentation doesn't declare functions properly #125018
Description
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
Activity
serhiy-storchaka commentedon Oct 6, 2024
Use triple backticks
:func:`importlib.metadata.version`.webknjaz commentedon Oct 6, 2024
@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 commentedon Oct 6, 2024
I meant that you can use triple quotes to quote text containing single or double backquotes in Markdown.
ncoghlan commentedon Oct 6, 2024
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 ).
pythongh-125018: Add importlib.metadata semantic link targets
ncoghlan commentedon Oct 6, 2024
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 commentedon Oct 6, 2024
One stray backtick still renders for me, though..
gh-125018: Add importlib.metadata semantic link targets (#125027)
pythongh-125018: Add importlib.metadata semantic link targets (python…
[3.12] gh-125018: Add importlib.metadata semantic link targets (GH-12…
pythongh-125018: Fix role syntax
gh-125018: Fix role syntax (#125050)
pythongh-125018: Fix role syntax (pythonGH-125050)
[3.12] gh-125018: Fix role syntax (GH-125050) (#125055)
[3.13] gh-125018: Add importlib.metadata semantic link targets (GH-12…
pythongh-125018: Fix role syntax (pythonGH-125050)
[3.13] gh-125018: Fix role syntax (GH-125050) (#125080)
ncoghlan commentedon Oct 8, 2024
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).