Use _parse_str_to_doctree() in Builder.read_doc() (#13676)

Author: AA-Turner

sphinx/builders/__init__.py

@@ -11,7 +11,6 @@
 from typing import TYPE_CHECKING, final
 
 from docutils import nodes
-from docutils.utils import DependencyList
 
 from sphinx._cli.util.colour import bold
 from sphinx.deprecation import _deprecation_warning
@@ -23,16 +22,12 @@
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
 from sphinx.locale import __
-from sphinx.util import (
-    get_filetype,
-    logging,
-    rst,
-)
+from sphinx.util import get_filetype, logging
 from sphinx.util._importer import import_object
 from sphinx.util._pathlib import _StrPathProperty
 from sphinx.util.build_phase import BuildPhase
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import sphinx_domains
+from sphinx.util.docutils import _parse_str_to_doctree
 from sphinx.util.i18n import CatalogRepository, docname_to_domain
 from sphinx.util.osutil import ensuredir, relative_uri, relpath
 from sphinx.util.parallel import (
@@ -644,26 +639,33 @@ def read_doc(self, docname: str, *, _cache: bool = True) -> None:
         if docutils_conf.is_file():
             env.note_dependency(docutils_conf)
 
-        filename = str(env.doc2path(docname))
-        filetype = get_filetype(self._app.config.source_suffix, filename)
-        publisher = self._registry._get_publisher(
-            filetype, config=self.config, env=self.env
+        filename = env.doc2path(docname)
+
+        # set up error_handler for the target document
+        error_handler = _UnicodeDecodeErrorHandler(docname)
+        codecs.register_error('sphinx', error_handler)  # type: ignore[arg-type]
+
+        # read the source file
+        content = filename.read_text(
+            encoding=env.settings['input_encoding'], errors='sphinx'
         )
-        self.env.current_document._parser = publisher.parser
-        # record_dependencies is mutable even though it is in settings,
-        # explicitly re-initialise for each document
-        publisher.settings.record_dependencies = DependencyList()
-        with (
-            sphinx_domains(env),
-            rst.default_role(docname, self.config.default_role),
-        ):
-            # set up error_handler for the target document
-            error_handler = _UnicodeDecodeErrorHandler(docname)
-            codecs.register_error('sphinx', error_handler)  # type: ignore[arg-type]
 
-            publisher.set_source(source_path=filename)
-            publisher.publish()
-            doctree = publisher.document
+        # TODO: move the "source-read" event to here.
+
+        filetype = get_filetype(self.config.source_suffix, filename)
+        parser = self._registry.create_source_parser(
+            filetype, config=self.config, env=env
+        )
+        doctree = _parse_str_to_doctree(
+            content,
+            filename=filename,
+            default_role=self.config.default_role,
+            default_settings=env.settings,
+            env=env,
+            events=self.events,
+            parser=parser,
+            transforms=self._registry.get_transforms(),
+        )
 
         # store time of reading, for outdated files detection
         env.all_docs[docname] = time.time_ns() // 1_000

sphinx/util/docutils.py

@@ -47,6 +47,7 @@
     from sphinx.builders import Builder
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
+    from sphinx.events import EventManager
     from sphinx.util.typing import RoleFunction
 
     class _LanguageModule(Protocol):
@@ -840,14 +841,17 @@ def _parse_str_to_doctree(
     default_role: str = '',
     default_settings: Mapping[str, Any],
     env: BuildEnvironment,
+    events: EventManager | None = None,
     parser: Parser,
     transforms: Sequence[type[Transform]] = (),
 ) -> nodes.document:
     env.current_document._parser = parser
 
     # Propagate exceptions by default when used programmatically:
     defaults = {'traceback': True, **default_settings}
-    settings = _get_settings(standalone.Reader, parser, defaults=defaults)
+    settings = _get_settings(
+        standalone.Reader, parser, defaults=defaults, read_config_files=True
+    )
     settings._source = str(filename)
 
     # Create root document node
@@ -872,6 +876,16 @@ def _parse_str_to_doctree(
     else:
         default_role_cm = nullcontext()  # type: ignore[assignment]
     with sphinx_domains(env), default_role_cm:
+        # TODO: Move the stanza below to Builder.read_doc(), within
+        #       a sphinx_domains() context manager.
+        #       This will require changes to IntersphinxDispatcher and/or
+        #       CustomReSTDispatcher.
+        if events is not None:
+            # emit "source-read" event
+            arg = [content]
+            events.emit('source-read', env.current_document.docname, arg)
+            content = arg[0]
+
         # parse content to abstract syntax tree
         parser.parse(content, document)
         document.current_source = document.current_line = None

tests/test_directives/test_directive_object_description.py

@@ -31,7 +31,7 @@ def _doctree_for_test(
     parser = registry.create_source_parser('restructuredtext', config=config, env=env)
     return _parse_str_to_doctree(
         content,
-        filename=env.doc2path(docname),
+        filename=filename,
         default_settings={'env': env},
         env=env,
         parser=parser,