singlehtml: Use same-document hyperlinks for internal project references

CHANGES.rst

@@ -4,6 +4,10 @@ Release 7.4.6 (in development)
 Bugs fixed
 ----------
 
+* #11970: singlehtml builder: make target URIs to be same-document references in
+  the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`, e.g., ``index.html#foo``
+  becomes ``#foo``. (note: continuation of a partial fix added in v7.3.0)
+  Patch by Eric Norige, James Addison.
 
 Release 7.4.5 (released Jul 16, 2024)
 =====================================

sphinx/builders/singlehtml.py

@@ -52,7 +52,6 @@ def get_relative_uri(self, from_: str, to: str, typ: str | None = None) -> str:
 
     def fix_refuris(self, tree: Node) -> None:
         # fix refuris with double anchor
-        fname = self.config.root_doc + self.out_suffix
         for refnode in tree.findall(nodes.reference):
             if 'refuri' not in refnode:
                 continue
@@ -62,7 +61,8 @@ def fix_refuris(self, tree: Node) -> None:
                 continue
             hashindex = refuri.find('#', hashindex + 1)
             if hashindex >= 0:
-                refnode['refuri'] = fname + refuri[hashindex:]
+                # all references are on the same page...
+                refnode['refuri'] = refuri[hashindex:]
 
     def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any) -> str:
         if isinstance(includehidden := kwargs.get('includehidden'), str):

tests/test_builders/test_build_html_tocdepth.py

@@ -1,4 +1,6 @@
 """Test the HTML builder and check output against XPath."""
+from collections.abc import Sequence
+from xml.etree.ElementTree import Element
 
 import pytest
 
@@ -52,9 +54,15 @@ def test_tocdepth(app, cached_etree_parse, fname, path, check, be_found):
     check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found)
 
 
+def _intradocument(nodes: Sequence[Element]) -> None:
+    for node in nodes:
+        assert 'href' in node.attrib
+        assert node.attrib['href'].startswith('#')
+
+
 @pytest.mark.parametrize("expect", [
-    (".//li[@class='toctree-l3']/a", '1.1.1. Foo A1', True),
-    (".//li[@class='toctree-l3']/a", '1.2.1. Foo B1', True),
+    (".//li[@class='toctree-l3']/a[.='1.1.1. Foo A1']", _intradocument),
+    (".//li[@class='toctree-l3']/a[.='1.2.1. Foo B1']", _intradocument),
     (".//li[@class='toctree-l3']/a", '2.1.1. Bar A1', False),
     (".//li[@class='toctree-l3']/a", '2.2.1. Bar B1', False),