Fix intersphinx reftitle for non-numeric versions (#13737)

szkarpinski · web-flow · commit 8949df498fdf · 2025-07-19T11:34:06.000+01:00
Signed-off-by: Szymon Karpiński &lt;skarpinski@nvidia.com&gt;
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -103,6 +103,7 @@ Contributors
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
 * Steve Piercy -- documentation improvements
+* Szymon Karpinski -- intersphinx improvements
 * \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -95,6 +95,8 @@ Bugs fixed
   Patch by Jean-François B.
 * #13685: gettext: Correctly ignore trailing backslashes.
   Patch by Bénédikt Tran.
+* #13712: intersphinx: Don't add "v" prefix to non-numeric versions.
+  Patch by Szymon Karpinski.
 
 Testing
 -------
diff --git a/sphinx/ext/intersphinx/_resolve.py b/sphinx/ext/intersphinx/_resolve.py
@@ -46,7 +46,12 @@ def _create_element_from_result(
         # get correct path in case of subdirectories
         uri = (_relative_path(Path(), Path(node['refdoc']).parent) / uri).as_posix()
     if inv_item.project_version:
-        reftitle = _('(in %s v%s)') % (inv_item.project_name, inv_item.project_version)
+        if not inv_item.project_version[0].isdigit():
+            # Do not append 'v' to non-numeric version
+            version = inv_item.project_version
+        else:
+            version = f'v{inv_item.project_version}'
+        reftitle = _('(in %s %s)') % (inv_item.project_name, version)
     else:
         reftitle = _('(in %s)') % (inv_item.project_name,)
 
diff --git a/tests/test_extensions/test_ext_intersphinx.py b/tests/test_extensions/test_ext_intersphinx.py
@@ -35,6 +35,7 @@
     INVENTORY_V2,
     INVENTORY_V2_AMBIGUOUS_TERMS,
     INVENTORY_V2_NO_VERSION,
+    INVENTORY_V2_TEXT_VERSION,
 )
 from tests.utils import http_server
 
@@ -900,3 +901,25 @@ def log_message(*args, **kwargs):
             srcdir=None,
             cache_path=None,
         )
+
+
+@pytest.mark.sphinx('html', testroot='root')
+def test_inventory_text_version(tmp_path, app):
+    inv_file = tmp_path / 'inventory'
+    inv_file.write_bytes(INVENTORY_V2_TEXT_VERSION)
+    set_config(
+        app,
+        {
+            'python': ('https://docs.python.org/', str(inv_file)),
+        },
+    )
+
+    # load the inventory and check if non-numeric version is handled correctly
+    validate_intersphinx_mapping(app, app.config)
+    load_mappings(app)
+
+    rn = reference_check(app, 'py', 'mod', 'module1', 'foo')
+    assert isinstance(rn, nodes.reference)
+    assert rn['refuri'] == 'https://docs.python.org/foo.html#module-module1'
+    assert rn['reftitle'] == '(in foo stable)'
+    assert rn[0].astext() == 'Long Module desc'
diff --git a/tests/test_util/intersphinx_data.py b/tests/test_util/intersphinx_data.py
@@ -62,3 +62,12 @@
 b term std:term -1 document.html#id5 -
 B term std:term -1 document.html#B -
 """)
+
+INVENTORY_V2_TEXT_VERSION: Final[bytes] = b"""\
+# Sphinx inventory version 2
+# Project: foo
+# Version: stable
+# The remainder of this file is compressed with zlib.
+""" + zlib.compress(b"""\
+module1 py:module 0 foo.html#module-module1 Long Module desc
+""")
