singlehtml: deprecate the 'fix_refuris' helper function (#13037)

Co-authored-by: Adam Turner <[email protected]>

Author: jayaddison

CHANGES.rst

@@ -12,6 +12,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* #13037: Deprecate the ``SingleHTMLBuilder.fix_refuris`` method.
+  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
+     - 10.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 RemovedInSphinx10Warning
 from sphinx.environment.adapters.toctree import global_toctree_for_doc
 from sphinx.locale import __
 from sphinx.util import logging
@@ -52,6 +54,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 10. '
+            'Please report malformed URIs generated by the Sphinx singlehtml '
+            'builder as bugreports.'
+        )
+        warnings.warn(deprecation_msg, RemovedInSphinx10Warning, stacklevel=2)
+
         # fix refuris with double anchor
         for refnode in tree.findall(nodes.reference):
             if 'refuri' not in refnode:
@@ -78,8 +88,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 +97,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 +147,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: