From c93723b80396959e19442f7058ad3412eaf11468 Mon Sep 17 00:00:00 2001
From: James Addison <55152140+jayaddison@users.noreply.github.com>
Date: Wed, 13 Nov 2024 23:15:00 +0000
Subject: [PATCH] singlehtml: deprecate the 'fix_refuris' helper function
 (#13037)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
---
 CHANGES.rst                   |  3 +++
 doc/extdev/deprecated.rst     |  5 +++++
 sphinx/builders/singlehtml.py | 14 ++++++++++----
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index b47f417e9a..ca123d89f4 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -12,6 +12,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* #13037: Deprecate the ``SingleHTMLBuilder.fix_refuris`` method.
+  Patch by James Addison.
+
 Features added
 --------------
 
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index f4d8f6a7f0..f459e80c5f 100644
--- a/doc/extdev/deprecated.rst
+++ b/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
diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py
index 2a6991f1d6..32dfee270b 100644
--- a/sphinx/builders/singlehtml.py
+++ b/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 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         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 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         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 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         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 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         )
         # if there is no toctree, toc is None
         if toctree:
-            self.fix_refuris(toctree)
             toc = self.render_partial(toctree)['fragment']
             display_toc = True
         else: