diff --git a/CHANGES.rst b/CHANGES.rst index b47f417e9a1..ecf4084c1cf 100644 --- a/CHANGES.rst +++ b/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 -------------- diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index f4d8f6a7f08..24ad3609ae1 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 + - 9.0 + - N/A + * - ``sphinx.util.FilenameUniqDict`` - 8.1 - 10.0 diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py index 2a6991f1d68..873224b982f 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 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: