python3-sphinx: backport patch to fix singlehtml URIs

The singlehtml builder creates broken links, as reported on the
yocto-docs list[1].

This issue was also reported upstream[2], and the temporary fix is to
revert commit c93723b80396 ("singlehtml: deprecate the 'fix_refuris'
helper function (#13037)") in sphinx.

Backport the revert commit as a patch in OE-Core.

[1]: https://lore.kernel.org/r/d8d48a98-edb6-4e30-a49b-0a9b52b14216@bytesatwork.ch
[2]: https://github.com/sphinx-doc/sphinx/issues/14221

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Mathieu Dubois-Briand <mathieu.dubois-briand@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

diff --git a/meta/recipes-devtools/python/python3-sphinx/0001-Revert-singlehtml-deprecate-the-fix_refuris-helper-f.patch b/meta/recipes-devtools/python/python3-sphinx/0001-Revert-singlehtml-deprecate-the-fix_refuris-helper-f.patch
new file mode 100644 (file)
index 0000000..1adf82d
--- /dev/null
+++ b/meta/recipes-devtools/python/python3-sphinx/0001-Revert-singlehtml-deprecate-the-fix_refuris-helper-f.patch
@@ -0,0 +1,72 @@
+From 323350c9c4df6be0935e7237ce20add8ccd1bb13 Mon Sep 17 00:00:00 2001
+From: James Addison <jay@jp-hosting.net>
+Date: Sun, 4 Jan 2026 20:51:55 +0000
+Subject: [PATCH] Revert "singlehtml: deprecate the 'fix_refuris' helper
+ function (#13037)"
+
+This reverts commit c93723b80396959e19442f7058ad3412eaf11468.
+
+Conflicts:
+       CHANGES.rst
+       doc/extdev/deprecated.rst
+       sphinx/builders/singlehtml.py
+
+Upstream-Status: Submitted [https://github.com/sphinx-doc/sphinx/pull/14241/changes/d5db93897a038c84afaad28e17c051182dbbffc7]
+
+Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
+---
+ sphinx/builders/singlehtml.py | 13 ++++---------
+ 1 file changed, 4 insertions(+), 9 deletions(-)
+
+diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py
+index 1888f6679..f895077df 100644
+--- a/sphinx/builders/singlehtml.py
++++ b/sphinx/builders/singlehtml.py
+@@ -9,7 +9,6 @@
+ 
+ from sphinx._cli.util.colour import darkgreen
+ 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,14 +51,6 @@ 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:
+@@ -86,6 +77,8 @@ def _get_local_toctree(
+         toctree = global_toctree_for_doc(
+             self.env, docname, self, tags=self.tags, collapse=collapse, **kwargs
+         )
++        if toctree is not None:
++            self.fix_refuris(toctree)
+         return self.render_partial(toctree)['fragment']
+ 
+     def assemble_doctree(self) -> nodes.document:
+@@ -95,6 +88,7 @@ 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, ...]]]:
+@@ -145,6 +139,7 @@ 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:

diff --git a/meta/recipes-devtools/python/python3-sphinx_9.1.0.bb b/meta/recipes-devtools/python/python3-sphinx_9.1.0.bb
index 24e95da10d15b5a0c9c7924f08324ddf56e319aa..76f904d708f4d97195937fafa137e7c1903a3ec2 100644 (file)
--- a/meta/recipes-devtools/python/python3-sphinx_9.1.0.bb
+++ b/meta/recipes-devtools/python/python3-sphinx_9.1.0.bb
@@ -6,6 +6,8 @@ LIC_FILES_CHKSUM = "file://LICENSE.rst;md5=e30c37a2b7fb0afa3adc0d72b85e8b04"
 
 SRC_URI[sha256sum] = "7741722357dd75f8190766926071fed3bdc211c74dd2d7d4df5404da95930ddb"
 
+SRC_URI += "file://0001-Revert-singlehtml-deprecate-the-fix_refuris-helper-f.patch"
+
 inherit python_flit_core pypi
 
 do_install:append () {