From acdf4a86980efdb37146169fc09d435e54a4a47d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sat, 7 Jun 2025 17:25:11 +0100 Subject: [PATCH] Use an explicit tags parameter for ``global_toctree_for_doc()`` (#13631) --- sphinx/builders/__init__.py | 22 ++++++++++++++----- sphinx/builders/_epub_base.py | 12 ++++++++-- sphinx/builders/epub3.py | 6 ++++- sphinx/builders/html/__init__.py | 2 +- sphinx/builders/singlehtml.py | 4 ++-- sphinx/environment/__init__.py | 4 +++- sphinx/environment/adapters/toctree.py | 17 ++++++++++++-- .../test_environment_toctree.py | 17 ++++++++++---- .../test_ext_inheritance_diagram.py | 2 +- tests/test_extensions/test_ext_math.py | 2 +- 10 files changed, 68 insertions(+), 20 deletions(-) diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index fb8bd75786..7060227374 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -772,7 +772,9 @@ class Builder: len(docnames), self._app.verbosity, ): - _write_docname(docname, app=self._app, env=self.env, builder=self) + _write_docname( + docname, app=self._app, env=self.env, builder=self, tags=self.tags + ) def _write_parallel(self, docnames: Sequence[str], nproc: int) -> None: def write_process(docs: list[tuple[str, nodes.document]]) -> None: @@ -782,7 +784,9 @@ class Builder: # warm up caches/compile templates using the first document firstname, docnames = docnames[0], docnames[1:] - _write_docname(firstname, app=self._app, env=self.env, builder=self) + _write_docname( + firstname, app=self._app, env=self.env, builder=self, tags=self.tags + ) tasks = ParallelTasks(nproc) chunks = make_chunks(docnames, nproc) @@ -804,7 +808,9 @@ class Builder: for chunk in chunks: arg = [] for docname in chunk: - doctree = self.env.get_and_resolve_doctree(docname, self) + doctree = self.env.get_and_resolve_doctree( + docname, self, tags=self.tags + ) self.write_doc_serialized(docname, doctree) arg.append((docname, doctree)) tasks.add_task(write_process, arg, on_chunk_done) @@ -871,11 +877,17 @@ class Builder: def _write_docname( - docname: str, /, *, app: Sphinx, env: BuildEnvironment, builder: Builder + docname: str, + /, + *, + app: Sphinx, + env: BuildEnvironment, + builder: Builder, + tags: Tags, ) -> None: """Write a single document.""" app.phase = BuildPhase.RESOLVING - doctree = env.get_and_resolve_doctree(docname, builder=builder) + doctree = env.get_and_resolve_doctree(docname, builder=builder, tags=tags) app.phase = BuildPhase.WRITING builder.write_doc_serialized(docname, doctree) builder.write_doc(docname, doctree) diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py index 28a7553da5..1bd4846bf0 100644 --- a/sphinx/builders/_epub_base.py +++ b/sphinx/builders/_epub_base.py @@ -233,7 +233,11 @@ class EpubBuilder(StandaloneHTMLBuilder): and pre and post files not managed by Sphinx. """ doctree = self.env.get_and_resolve_doctree( - self.config.master_doc, self, prune_toctrees=False, includehidden=True + self.config.master_doc, + self, + tags=self.tags, + prune_toctrees=False, + includehidden=True, ) self.refnodes = self.get_refnodes(doctree, []) master_dir = Path(self.config.master_doc).parent @@ -765,7 +769,11 @@ class EpubBuilder(StandaloneHTMLBuilder): if self.config.epub_tocscope == 'default': doctree = self.env.get_and_resolve_doctree( - self.config.root_doc, self, prune_toctrees=False, includehidden=False + self.config.root_doc, + self, + tags=self.tags, + prune_toctrees=False, + includehidden=False, ) refnodes = self.get_refnodes(doctree, []) self.toc_add_files(refnodes) diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py index 2ea66c34b8..c17be8bd4e 100644 --- a/sphinx/builders/epub3.py +++ b/sphinx/builders/epub3.py @@ -190,7 +190,11 @@ class Epub3Builder(_epub_base.EpubBuilder): if self.config.epub_tocscope == 'default': doctree = self.env.get_and_resolve_doctree( - self.config.root_doc, self, prune_toctrees=False, includehidden=False + self.config.root_doc, + self, + tags=self.tags, + prune_toctrees=False, + includehidden=False, ) refnodes = self.get_refnodes(doctree, []) self.toc_add_files(refnodes) diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py index 1ba026a61d..a5f725e292 100644 --- a/sphinx/builders/html/__init__.py +++ b/sphinx/builders/html/__init__.py @@ -1029,7 +1029,7 @@ class StandaloneHTMLBuilder(Builder): if kwargs.get('maxdepth') == '': # NoQA: PLC1901 kwargs.pop('maxdepth') toctree = global_toctree_for_doc( - self.env, docname, self, collapse=collapse, **kwargs + self.env, docname, self, tags=self.tags, collapse=collapse, **kwargs ) return self.render_partial(toctree)['fragment'] diff --git a/sphinx/builders/singlehtml.py b/sphinx/builders/singlehtml.py index c95603927c..1888f6679d 100644 --- a/sphinx/builders/singlehtml.py +++ b/sphinx/builders/singlehtml.py @@ -84,7 +84,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): if kwargs.get('maxdepth') == '': # NoQA: PLC1901 kwargs.pop('maxdepth') toctree = global_toctree_for_doc( - self.env, docname, self, collapse=collapse, **kwargs + self.env, docname, self, tags=self.tags, collapse=collapse, **kwargs ) return self.render_partial(toctree)['fragment'] @@ -141,7 +141,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, Any]: # no relation links... toctree = global_toctree_for_doc( - self.env, self.config.root_doc, self, collapse=False + self.env, self.config.root_doc, self, tags=self.tags, collapse=False ) # if there is no toctree, toc is None if toctree: diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index 846a1bbde9..fd611639e9 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -701,6 +701,8 @@ class BuildEnvironment: self, docname: str, builder: Builder, + *, + tags: Tags, doctree: nodes.document | None = None, prune_toctrees: bool = True, includehidden: bool = False, @@ -770,7 +772,7 @@ class BuildEnvironment: titles_only=titles_only, collapse=collapse, includehidden=includehidden, - tags=builder.tags, + tags=self._tags, ) def resolve_references( diff --git a/sphinx/environment/adapters/toctree.py b/sphinx/environment/adapters/toctree.py index 90344f185d..4708383d64 100644 --- a/sphinx/environment/adapters/toctree.py +++ b/sphinx/environment/adapters/toctree.py @@ -2,12 +2,14 @@ from __future__ import annotations +import warnings from typing import TYPE_CHECKING, TypeVar from docutils import nodes from docutils.nodes import Element from sphinx import addnodes +from sphinx.deprecation import RemovedInSphinx10Warning from sphinx.locale import __ from sphinx.util import logging, url_re from sphinx.util.matching import Matcher @@ -69,6 +71,8 @@ def global_toctree_for_doc( env: BuildEnvironment, docname: str, builder: Builder, + *, + tags: Tags = ..., # type: ignore[assignment] collapse: bool = False, includehidden: bool = True, maxdepth: int = 0, @@ -78,6 +82,15 @@ def global_toctree_for_doc( This gives the global ToC, with all ancestors and their siblings. """ + if tags is ...: + warnings.warn( + "'tags' will become a required keyword argument " + 'for global_toctree_for_doc() in Sphinx 10.0.', + RemovedInSphinx10Warning, + stacklevel=2, + ) + tags = builder.tags + resolved = ( _resolve_toctree( env, @@ -89,7 +102,7 @@ def global_toctree_for_doc( titles_only=titles_only, collapse=collapse, includehidden=includehidden, - tags=builder.tags, + tags=tags, ) for toctree_node in env.master_doctree.findall(addnodes.toctree) ) @@ -582,5 +595,5 @@ class TocTree: **kwargs: Any, ) -> Element | None: return global_toctree_for_doc( - self.env, docname, builder, collapse=collapse, **kwargs + self.env, docname, builder, tags=builder.tags, collapse=collapse, **kwargs ) diff --git a/tests/test_environment/test_environment_toctree.py b/tests/test_environment/test_environment_toctree.py index f6b849c5be..22474daef5 100644 --- a/tests/test_environment/test_environment_toctree.py +++ b/tests/test_environment/test_environment_toctree.py @@ -614,7 +614,9 @@ def test_document_toc_tocdepth(app): @pytest.mark.test_params(shared_result='test_environment_toctree_basic') def test_global_toctree_for_doc(app): app.build() - toctree = global_toctree_for_doc(app.env, 'index', app.builder, collapse=False) + toctree = global_toctree_for_doc( + app.env, 'index', app.builder, tags=app.tags, collapse=False + ) assert_node( toctree, [ @@ -676,7 +678,9 @@ def test_global_toctree_for_doc(app): @pytest.mark.test_params(shared_result='test_environment_toctree_basic') def test_global_toctree_for_doc_collapse(app): app.build() - toctree = global_toctree_for_doc(app.env, 'index', app.builder, collapse=True) + toctree = global_toctree_for_doc( + app.env, 'index', app.builder, tags=app.tags, collapse=True + ) assert_node( toctree, [ @@ -723,7 +727,7 @@ def test_global_toctree_for_doc_collapse(app): def test_global_toctree_for_doc_maxdepth(app): app.build() toctree = global_toctree_for_doc( - app.env, 'index', app.builder, collapse=False, maxdepth=3 + app.env, 'index', app.builder, tags=app.tags, collapse=False, maxdepth=3 ) assert_node( toctree, @@ -814,7 +818,12 @@ def test_global_toctree_for_doc_maxdepth(app): def test_global_toctree_for_doc_includehidden(app): app.build() toctree = global_toctree_for_doc( - app.env, 'index', app.builder, collapse=False, includehidden=False + app.env, + 'index', + app.builder, + tags=app.tags, + collapse=False, + includehidden=False, ) assert_node( toctree, diff --git a/tests/test_extensions/test_ext_inheritance_diagram.py b/tests/test_extensions/test_ext_inheritance_diagram.py index 4153113d12..f98d424eda 100644 --- a/tests/test_extensions/test_ext_inheritance_diagram.py +++ b/tests/test_extensions/test_ext_inheritance_diagram.py @@ -293,7 +293,7 @@ def test_inheritance_diagram_latex_alias(app): app.config.inheritance_alias = {'test.Foo': 'alias.Foo'} app.build(force_all=True) - doc = app.env.get_and_resolve_doctree('index', app) + doc = app.env.get_and_resolve_doctree('index', app.builder, tags=app.tags) aliased_graph = doc.children[0].children[3]['graph'].class_info assert len(aliased_graph) == 4 assert ( diff --git a/tests/test_extensions/test_ext_math.py b/tests/test_extensions/test_ext_math.py index 02d215bef0..2dbc93629f 100644 --- a/tests/test_extensions/test_ext_math.py +++ b/tests/test_extensions/test_ext_math.py @@ -323,7 +323,7 @@ def test_imgmath_numfig_html(app: SphinxTestApp) -> None: def test_math_compat(app): with warnings.catch_warnings(record=True): app.build(force_all=True) - doctree = app.env.get_and_resolve_doctree('index', app.builder) + doctree = app.env.get_and_resolve_doctree('index', app.builder, tags=app.tags) assert_node( doctree,