Use an explicit tags parameter for `global_toctree_for_doc()` (#13631)

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)

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)

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)

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']
 

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:

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(

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
         )

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,

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 (

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,