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/[email protected]
[2]: https://github.com/sphinx-doc/sphinx/issues/14221
Signed-off-by: Antonin Godard <[email protected]>
---
...lehtml-deprecate-the-fix_refuris-helper-f.patch | 72 ++++++++++++++++++++++
.../python/python3-sphinx_9.1.0.bb | 2 +
2 files changed, 74 insertions(+)
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
index 00000000000..1adf82d7ef3
--- /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 <[email protected]>
+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 <[email protected]>
+---
+ 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 24e95da10d1..76f904d708f 100644
--- 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 () {
---
base-commit: d9ec9e20eebc062d084dd76b59d665994e0cb51b
change-id: 20260217-fix-sphinx-singlehtml-uris-44600bd5f15a
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#231235):
https://lists.openembedded.org/g/openembedded-core/message/231235
Mute This Topic: https://lists.openembedded.org/mt/117854459/21656
Group Owner: [email protected]
Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub
[[email protected]]
-=-=-=-=-=-=-=-=-=-=-=-
