Prefer current_document.docname (#13669)

AA-Turner · web-flow · commit be6593b0de9c · 2025-06-16T20:37:08.000+01:00
diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py
@@ -165,7 +165,7 @@ def add_recipe(self, signature, ingredients):
             name,
             signature,
             'Recipe',
-            self.env.docname,
+            self.env.current_document.docname,
             anchor,
             0,
         ))
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
@@ -44,7 +44,7 @@ def run(self):
             self.env.todo_all_todos = []
 
         self.env.todo_all_todos.append({
-            'docname': self.env.docname,
+            'docname': self.env.current_document.docname,
             'lineno': self.lineno,
             'todo': todo_node.deepcopy(),
             'target': targetnode,
diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py
@@ -40,7 +40,7 @@ class FootnoteDocnameUpdater(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(*self.TARGET_NODES)
         for node in matcher.findall(self.document):
-            node['docname'] = self.env.docname
+            node['docname'] = self.env.current_document.docname
 
 
 class SubstitutionDefinitionsRemover(SphinxPostTransform):
diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py
@@ -261,7 +261,7 @@ def _add_uri(self, uri: str, node: nodes.Element) -> None:
         """
         builder = cast('CheckExternalLinksBuilder', self.env._app.builder)
         hyperlinks = builder.hyperlinks
-        docname = self.env.docname
+        docname = self.env.current_document.docname
 
         if newuri := self.env.events.emit_firstresult('linkcheck-process-uri', uri):
             uri = newuri
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
@@ -63,7 +63,7 @@ class TocTree(SphinxDirective):
 
     def run(self) -> list[Node]:
         subnode = addnodes.toctree()
-        subnode['parent'] = self.env.docname
+        subnode['parent'] = self.env.current_document.docname
 
         # (title, ref) pairs, where ref may be a document, or an external link,
         # and title may be None if the document's title is to be used
@@ -90,7 +90,7 @@ def parse_content(self, toctree: addnodes.toctree) -> None:
         """Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content."""
         generated_docnames = frozenset(StandardDomain._virtual_doc_names)
         suffixes = self.config.source_suffix
-        current_docname = self.env.docname
+        current_docname = self.env.current_document.docname
         glob = toctree['glob']
 
         # glob target documents
@@ -267,7 +267,7 @@ def run(self) -> list[Node]:
         if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
             logger.warning(
                 __('.. acks content is not a list'),
-                location=(self.env.docname, self.lineno),
+                location=(self.env.current_document.docname, self.lineno),
             )
             return []
         return [addnodes.acks('', *children)]
@@ -290,7 +290,7 @@ def run(self) -> list[Node]:
         if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
             logger.warning(
                 __('.. hlist content is not a list'),
-                location=(self.env.docname, self.lineno),
+                location=(self.env.current_document.docname, self.lineno),
             )
             return []
         fulllist = children[0]
@@ -388,7 +388,7 @@ def _insert_input(include_lines: list[str], source: str) -> None:
             text = '\n'.join(include_lines[:-2])
 
             path = Path(relpath(Path(source).resolve(), start=self.env.srcdir))
-            docname = self.env.docname
+            docname = self.env.current_document.docname
 
             # Emit the "include-read" event
             arg = [text]
diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py
@@ -72,11 +72,11 @@ def run(self) -> list[Node]:
                         'an absolute path as a relative path from source directory. '
                         'Please update your document.'
                     ),
-                    location=(env.docname, self.lineno),
+                    location=(env.current_document.docname, self.lineno),
                 )
             else:
                 abspath = env.srcdir / self.options['file'][1:]
-                doc_dir = env.doc2path(env.docname).parent
+                doc_dir = env.doc2path(env.current_document.docname).parent
                 self.options['file'] = relpath(abspath, doc_dir)
 
         return super().run()
@@ -162,7 +162,7 @@ def run(self) -> list[Node]:
             latex,
             latex,
             classes=self.options.get('class', []),
-            docname=self.env.docname,
+            docname=self.env.current_document.docname,
             number=None,
             label=label,
         )
@@ -180,15 +180,17 @@ def add_target(self, ret: list[Node]) -> None:
         # assign label automatically if math_number_all enabled
         if node['label'] == '' or (self.config.math_number_all and not node['label']):  # NoQA: PLC1901
             seq = self.env.new_serialno('sphinx.ext.math#equations')
-            node['label'] = f'{self.env.docname}:{seq}'
+            node['label'] = f'{self.env.current_document.docname}:{seq}'
 
         # no targets and numbers are needed
         if not node['label']:
             return
 
         # register label to domain
         domain = self.env.domains.math_domain
-        domain.note_equation(self.env.docname, node['label'], location=node)
+        domain.note_equation(
+            self.env.current_document.docname, node['label'], location=node
+        )
         node['number'] = domain.get_equation_number_for(node['label'])
 
         # add target node
diff --git a/sphinx/domains/c/__init__.py b/sphinx/domains/c/__init__.py
@@ -156,7 +156,7 @@ def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
             parent=target_symbol,
             ident=symbol.ident,
             declaration=decl_clone,
-            docname=self.env.docname,
+            docname=self.env.current_document.docname,
             line=self.get_source_info()[1],
         )
 
@@ -259,7 +259,9 @@ def handle_signature(self, sig: str, signode: TextElement) -> ASTDeclaration:
 
         try:
             symbol = parent_symbol.add_declaration(
-                ast, docname=self.env.docname, line=self.get_source_info()[1]
+                ast,
+                docname=self.env.current_document.docname,
+                line=self.get_source_info()[1],
             )
             # append the new declaration to the sibling list
             assert symbol.siblingAbove is None
diff --git a/sphinx/domains/changeset.py b/sphinx/domains/changeset.py
@@ -135,7 +135,7 @@ def note_changeset(self, node: addnodes.versionmodified) -> None:
         objname = self.env.current_document.obj_desc_name
         changeset = ChangeSet(
             node['type'],
-            self.env.docname,
+            self.env.current_document.docname,
             node.line,  # type: ignore[arg-type]
             module,
             objname,
diff --git a/sphinx/domains/citation.py b/sphinx/domains/citation.py
@@ -83,7 +83,7 @@ def note_citation(self, node: nodes.citation) -> None:
 
     def note_citation_reference(self, node: pending_xref) -> None:
         docnames = self.citation_refs.setdefault(node['reftarget'], set())
-        docnames.add(self.env.docname)
+        docnames.add(self.env.current_document.docname)
 
     def check_consistency(self) -> None:
         for name, (docname, _labelid, lineno) in self.citations.items():
@@ -139,7 +139,7 @@ def apply(self, **kwargs: Any) -> None:
         domain = self.env.domains.citation_domain
         for node in self.document.findall(nodes.citation):
             # register citation node to domain
-            node['docname'] = self.env.docname
+            node['docname'] = self.env.current_document.docname
             domain.note_citation(node)
 
             # mark citation labels as not smartquoted
diff --git a/sphinx/domains/cpp/__init__.py b/sphinx/domains/cpp/__init__.py
@@ -219,7 +219,7 @@ def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
             templateParams=None,
             templateArgs=None,
             declaration=decl_clone,
-            docname=self.env.docname,
+            docname=self.env.current_document.docname,
             line=self.get_source_info()[1],
         )
 
@@ -374,7 +374,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> ASTDeclaration:
 
         try:
             symbol = parent_symbol.add_declaration(
-                ast, docname=self.env.docname, line=self.get_source_info()[1]
+                ast,
+                docname=self.env.current_document.docname,
+                line=self.get_source_info()[1],
             )
             # append the new declaration to the sibling list
             assert symbol.siblingAbove is None
diff --git a/sphinx/domains/index.py b/sphinx/domains/index.py
@@ -47,7 +47,7 @@ def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> Non
 
     def process_doc(self, env: BuildEnvironment, docname: str, document: Node) -> None:
         """Process a document after it is read by the environment."""
-        entries = self.entries.setdefault(env.docname, [])
+        entries = self.entries.setdefault(env.current_document.docname, [])
         for node in list(document.findall(addnodes.index)):
             node_entries = node['entries']
             try:
diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
@@ -363,7 +363,10 @@ def run(self) -> list[Node]:
             # Make a duplicate entry in 'objects' to facilitate searching for
             # the module in JavaScriptDomain.find_obj()
             domain.note_object(
-                mod_name, 'module', node_id, location=(self.env.docname, self.lineno)
+                mod_name,
+                'module',
+                node_id,
+                location=(self.env.current_document.docname, self.lineno),
             )
 
             # The node order is: index node first, then target node
@@ -459,14 +462,14 @@ def note_object(
                 docname,
                 location=location,
             )
-        self.objects[fullname] = (self.env.docname, node_id, objtype)
+        self.objects[fullname] = (self.env.current_document.docname, node_id, objtype)
 
     @property
     def modules(self) -> dict[str, tuple[str, str]]:
         return self.data.setdefault('modules', {})  # modname -> docname, node_id
 
     def note_module(self, modname: str, node_id: str) -> None:
-        self.modules[modname] = (self.env.docname, node_id)
+        self.modules[modname] = (self.env.current_document.docname, node_id)
 
     def clear_doc(self, docname: str) -> None:
         for fullname, (pkg_docname, _node_id, _l) in list(self.objects.items()):
diff --git a/sphinx/domains/python/__init__.py b/sphinx/domains/python/__init__.py
@@ -818,7 +818,9 @@ def note_object(
                     other.docname,
                     location=location,
                 )
-        self.objects[name] = ObjectEntry(self.env.docname, node_id, objtype, aliased)
+        self.objects[name] = ObjectEntry(
+            self.env.current_document.docname, node_id, objtype, aliased
+        )
 
     @property
     def modules(self) -> dict[str, ModuleEntry]:
@@ -832,7 +834,7 @@ def note_module(
         .. versionadded:: 2.1
         """
         self.modules[name] = ModuleEntry(
-            docname=self.env.docname,
+            docname=self.env.current_document.docname,
             node_id=node_id,
             synopsis=synopsis,
             platform=platform,
diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py
@@ -266,7 +266,7 @@ def note_object(
                 location=location,
             )
 
-        self.objects[objtype, name] = (self.env.docname, node_id)
+        self.objects[objtype, name] = (self.env.current_document.docname, node_id)
 
     def clear_doc(self, docname: str) -> None:
         for (typ, name), (doc, _node_id) in list(self.objects.items()):
diff --git a/sphinx/domains/std/__init__.py b/sphinx/domains/std/__init__.py
@@ -308,7 +308,10 @@ def add_target_and_index(
         domain = self.env.domains.standard_domain
         for optname in signode.get('allnames', ()):
             domain.add_program_option(
-                currprogram, optname, self.env.docname, signode['ids'][0]
+                currprogram,
+                optname,
+                self.env.current_document.docname,
+                signode['ids'][0],
             )
 
         # create an index entry
@@ -857,7 +860,7 @@ def note_object(
                 docname,
                 location=location,
             )
-        self.objects[objtype, name] = (self.env.docname, labelid)
+        self.objects[objtype, name] = (self.env.current_document.docname, labelid)
 
     @property
     def _terms(self) -> dict[str, tuple[str, str]]:
@@ -871,7 +874,7 @@ def _note_term(self, term: str, labelid: str, location: Any = None) -> None:
         """
         self.note_object('term', term, labelid, location)
 
-        self._terms[term.lower()] = (self.env.docname, labelid)
+        self._terms[term.lower()] = (self.env.current_document.docname, labelid)
 
     @property
     def progoptions(self) -> dict[tuple[str | None, str], tuple[str, str]]:
diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py
@@ -788,7 +788,7 @@ def apply_post_transforms(self, doctree: nodes.document, docname: str) -> None:
         new = deepcopy(backup)
         new.docname = docname
         try:
-            # set env.docname during applying post-transforms
+            # set env.current_document.docname during applying post-transforms
             self.current_document = new
 
             transformer = SphinxTransformer(doctree)
diff --git a/sphinx/environment/collectors/asset.py b/sphinx/environment/collectors/asset.py
@@ -47,7 +47,7 @@ def merge_other(
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         """Process and rewrite image URIs."""
-        docname = app.env.docname
+        docname = app.env.current_document.docname
 
         for node in doctree.findall(nodes.image):
             # Map the mimetype to the corresponding image.  The writer may
@@ -156,7 +156,9 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
             if '://' in targetname:
                 node['refuri'] = targetname
             else:
-                rel_filename, filename = app.env.relfn2path(targetname, app.env.docname)
+                rel_filename, filename = app.env.relfn2path(
+                    targetname, app.env.current_document.docname
+                )
                 app.env.note_dependency(rel_filename)
                 if not os.access(filename, os.R_OK):
                     logger.warning(
@@ -168,7 +170,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
                     )
                     continue
                 node['filename'] = app.env.dlfiles.add_file(
-                    app.env.docname, rel_filename
+                    app.env.current_document.docname, rel_filename
                 ).as_posix()
 
 
diff --git a/sphinx/environment/collectors/metadata.py b/sphinx/environment/collectors/metadata.py
@@ -41,7 +41,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         if index is None:
             return
         elif isinstance(doctree[index], nodes.docinfo):
-            md = app.env.metadata[app.env.docname]
+            md = app.env.metadata[app.env.current_document.docname]
             for node in doctree[index]:  # type: ignore[attr-defined]
                 # nodes are multiply inherited...
                 if isinstance(node, nodes.authors):
diff --git a/sphinx/environment/collectors/title.py b/sphinx/environment/collectors/title.py
@@ -55,8 +55,8 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         else:
             # document has no title
             titlenode += nodes.Text(doctree.get('title', '<no title>'))
-        app.env.titles[app.env.docname] = titlenode
-        app.env.longtitles[app.env.docname] = longtitlenode
+        app.env.titles[app.env.current_document.docname] = titlenode
+        app.env.longtitles[app.env.current_document.docname] = longtitlenode
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
diff --git a/sphinx/environment/collectors/toctree.py b/sphinx/environment/collectors/toctree.py
@@ -65,7 +65,7 @@ def merge_other(
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         """Build a TOC from the doctree and store it in the inventory."""
-        docname = app.env.docname
+        docname = app.env.current_document.docname
         numentries = [0]  # nonlocal again...
 
         def build_toc(
diff --git a/sphinx/ext/autodoc/directive.py b/sphinx/ext/autodoc/directive.py
@@ -163,7 +163,7 @@ def run(self) -> list[Node]:
                 'An option to %s is either unknown or has an invalid value: %s',
                 self.name,
                 exc,
-                location=(self.env.docname, lineno),
+                location=(self.env.current_document.docname, lineno),
             )
             return []
 
diff --git a/sphinx/ext/autosectionlabel.py b/sphinx/ext/autosectionlabel.py
@@ -39,7 +39,7 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None:
         ):
             continue
         labelid = node['ids'][0]
-        docname = app.env.docname
+        docname = app.env.current_document.docname
         title = cast('nodes.title', node[0])
         ref_name = getattr(title, 'rawsource', title.astext())
         if app.config.autosectionlabel_prefix_document:
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
@@ -268,7 +268,7 @@ def run(self) -> list[Node]:
         nodes = self.get_table(items)
 
         if 'toctree' in self.options:
-            dirname = posixpath.dirname(self.env.docname)
+            dirname = posixpath.dirname(self.env.current_document.docname)
 
             tree_prefix = self.options['toctree'].strip()
             docnames = []
diff --git a/sphinx/ext/duration.py b/sphinx/ext/duration.py
@@ -37,7 +37,7 @@ def reading_durations(self) -> dict[str, float]:
         return self.data.setdefault('reading_durations', {})
 
     def note_reading_duration(self, duration: float) -> None:
-        self.reading_durations[self.env.docname] = duration
+        self.reading_durations[self.env.current_document.docname] = duration
 
     def clear(self) -> None:
         self.reading_durations.clear()
diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py
diff --git a/sphinx/ext/intersphinx/_resolve.py b/sphinx/ext/intersphinx/_resolve.py
diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py
diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py
diff --git a/sphinx/io.py b/sphinx/io.py
diff --git a/sphinx/roles.py b/sphinx/roles.py
diff --git a/sphinx/transforms/i18n.py b/sphinx/transforms/i18n.py
diff --git a/sphinx/transforms/post_transforms/__init__.py b/sphinx/transforms/post_transforms/__init__.py
diff --git a/sphinx/transforms/post_transforms/images.py b/sphinx/transforms/post_transforms/images.py
diff --git a/sphinx/transforms/references.py b/sphinx/transforms/references.py
diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py
diff --git a/sphinx/versioning.py b/sphinx/versioning.py
