Inline io.read_doc and explain why settings are copied

sphinx/builders/__init__.py

@@ -1,5 +1,6 @@
 """Builder superclass for all builders."""
 
+import codecs
 import pickle
 import time
 from os import path
@@ -14,10 +15,9 @@ from sphinx.environment import CONFIG_CHANGED_REASON, CONFIG_OK, BuildEnvironmen
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
 from sphinx.events import EventManager
-from sphinx.io import read_doc
 from sphinx.locale import __
-from sphinx.util import (get_filetype, import_object, logging, progress_message, rst,
-                         status_iterator)
+from sphinx.util import (UnicodeDecodeErrorHandler, get_filetype, import_object, logging,
+                         progress_message, rst, status_iterator)
 from sphinx.util.build_phase import BuildPhase
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.docutils import sphinx_domains
@@ -469,7 +469,17 @@ class Builder:
         filetype = get_filetype(self.app.config.source_suffix, filename)
         publisher = self.app.registry.get_publisher(self.app, filetype)
         with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role):
-            doctree = read_doc(publisher, docname, filename)
+            # set up error_handler for the target document
+            codecs.register_error('sphinx', UnicodeDecodeErrorHandler(docname))  # type: ignore
+
+            publisher.set_source(source_path=filename)
+            publisher.publish()
+            doctree = publisher.document
+
+            # The settings object is reused by the Publisher for each document.
+            # Becuase we modify the settings object in ``write_doctree``, we
+            # need to ensure that each doctree has an independent copy.
+            doctree.settings = doctree.settings.copy()
 
         # store time of reading, for outdated files detection
         # (Some filesystems have coarse timestamp resolution;

sphinx/io.py

@@ -1,5 +1,5 @@
 """Input/Output files"""
-import codecs
+
 from typing import TYPE_CHECKING, Any, List, Type
 
 from docutils import nodes
@@ -19,7 +19,7 @@ from sphinx.transforms import (AutoIndexUpgrader, DoctreeReadEvent, FigureAligne
 from sphinx.transforms.i18n import (Locale, PreserveTranslatableMessages,
                                     RemoveTranslatableInline)
 from sphinx.transforms.references import SphinxDomains
-from sphinx.util import UnicodeDecodeErrorHandler, logging
+from sphinx.util import logging
 from sphinx.util.docutils import LoggingReporter
 from sphinx.versioning import UIDTransform
 
@@ -152,21 +152,6 @@ class SphinxFileInput(FileInput):
         super().__init__(*args, **kwargs)
 
 
-def read_doc(publisher: Publisher, docname: str, filename: str) -> nodes.document:
-    """Parse a document and convert to doctree."""
-    # set up error_handler for the target document
-    error_handler = UnicodeDecodeErrorHandler(docname)
-    codecs.register_error('sphinx', error_handler)  # type: ignore
-
-    publisher.set_source(source_path=filename)
-    publisher.publish()
-
-    doctree = publisher.document
-    # settings get modified in ``write_doctree``; get a local copy
-    doctree.settings = doctree.settings.copy()
-    return doctree
-
-
 def create_publisher(app: "Sphinx", filetype: str) -> Publisher:
     reader = SphinxStandaloneReader()
     reader.setup(app)