singlehtml: deprecate 'fix_refuris' helper function

CHANGES.rst

@@ -11,6 +11,9 @@ Incompatible changes
 
 Deprecated
 ----------
+* #13037: Deprecate the ``SingleHTMLBuilder.fix_refuris`` method, with removal
+  planned for version 9.0 of Sphinx.
+  Patch by James Addison.
 
 Features added
 --------------

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder.fix_refuris``
+     - 8.2
+     - 9.0
+     - N/A
+
    * - ``sphinx.util.FilenameUniqDict``
      - 8.1
      - 10.0

sphinx/builders/singlehtml.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 
 from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.deprecation import RemovedInNextVersionWarning
 from sphinx.environment.adapters.toctree import global_toctree_for_doc
 from sphinx.locale import __
 from sphinx.util import logging
@@ -40,8 +42,10 @@ def get_outdated_docs(self) -> str | list[str]:  # type: ignore[override]
         return 'all documents'
 
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
-        if docname in self.env.all_docs:
-            # all references are on the same page...
+        # all references are on the same page...
+        if docname.startswith('#'):
+            return docname
+        elif docname in self.env.all_docs:
             return '#document-' + docname
         else:
             # chances are this is a html_additional_page
@@ -52,6 +56,14 @@ def get_relative_uri(self, from_: str, to: str, typ: str | None = None) -> str:
         return self.get_target_uri(to, typ)
 
     def fix_refuris(self, tree: Node) -> None:
+        deprecation_msg = (
+            "The 'SingleFileHTMLBuilder.fix_refuris' method is no longer used "
+            'within the builder and is planned for removal in Sphinx 9. '
+            'Please report malformed URIs generated by the Sphinx singlehtml '
+            'builder as bugreports.'
+        )
+        warnings.warn(deprecation_msg, RemovedInNextVersionWarning, stacklevel=2)
+
         # fix refuris with double anchor
         for refnode in tree.findall(nodes.reference):
             if 'refuri' not in refnode:
@@ -78,8 +90,6 @@ def _get_local_toctree(
         toctree = global_toctree_for_doc(
             self.env, docname, self, collapse=collapse, **kwargs
         )
-        if toctree is not None:
-            self.fix_refuris(toctree)
         return self.render_partial(toctree)['fragment']
 
     def assemble_doctree(self) -> nodes.document:
@@ -89,7 +99,6 @@ def assemble_doctree(self) -> nodes.document:
         tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master])
         tree['docname'] = master
         self.env.resolve_references(tree, master, self)
-        self.fix_refuris(tree)
         return tree
 
     def assemble_toc_secnumbers(self) -> dict[str, dict[str, tuple[int, ...]]]:
@@ -140,7 +149,6 @@ def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, A
         )
         # if there is no toctree, toc is None
         if toctree:
-            self.fix_refuris(toctree)
             toc = self.render_partial(toctree)['fragment']
             display_toc = True
         else: