refactor: Move env.read_doc() to Builder._read_doc()

CHANGES

@@ -51,6 +51,7 @@ Deprecated
 * ``Config.check_unicode()`` is deprecated
 * ``sphinx.application.CONFIG_FILENAME`` is deprecated
 * ``highlightlang`` directive is deprecated
+* ``env.read_doc()`` is deprecated
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_

doc/extdev/index.rst

@@ -203,6 +203,11 @@ The following is a list of deprecated interface.
      - 3.0
      - ``Builder.read()``
 
+   * - ``BuildEnvironment.read_doc()``
+     - 1.8
+     - 3.0
+     - ``Builder.read_doc()``
+
    * - ``BuildEnvironment._read_serial()``
      - 1.8
      - 3.0

sphinx/builders/__init__.py

@@ -9,6 +9,7 @@
     :license: BSD, see LICENSE for details.
 """
 
+import time
 import warnings
 from os import path
 
@@ -18,10 +19,12 @@ from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
+from sphinx.io import read_doc
 from sphinx.locale import __
-from sphinx.util import i18n, import_object, logging, status_iterator
+from sphinx.util import i18n, import_object, logging, 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
 from sphinx.util.i18n import find_catalog
 from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
 from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \
@@ -478,7 +481,7 @@ class Builder(object):
             # remove all inventory entries for that file
             self.app.emit('env-purge-doc', self.env, docname)
             self.env.clear_doc(docname)
-            self.env.read_doc(docname, self.app)
+            self.read_doc(docname)
 
     def _read_parallel(self, docnames, nproc):
         # type: (List[unicode], int) -> None
@@ -491,7 +494,7 @@ class Builder(object):
             # type: (List[unicode]) -> unicode
             self.env.app = self.app
             for docname in docs:
-                self.env.read_doc(docname, self.app)
+                self.read_doc(docname)
             # allow pickling self to send it back
             return BuildEnvironment.dumps(self.env)
 
@@ -511,6 +514,32 @@ class Builder(object):
         logger.info(bold('waiting for workers...'))
         tasks.join()
 
+    def read_doc(self, docname):
+        # type: (unicode) -> None
+        """Parse a file and add/update inventory entries for the doctree."""
+        self.env.prepare_settings(docname)
+
+        # Add confdir/docutils.conf to dependencies list if exists
+        docutilsconf = path.join(self.confdir, 'docutils.conf')
+        if path.isfile(docutilsconf):
+            self.env.note_dependency(docutilsconf)
+
+        with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role):
+            doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
+
+        # store time of reading, for outdated files detection
+        # (Some filesystems have coarse timestamp resolution;
+        # therefore time.time() can be older than filesystem's timestamp.
+        # For example, FAT32 has 2sec timestamp resolution.)
+        self.env.all_docs[docname] = max(time.time(),
+                                         path.getmtime(self.env.doc2path(docname)))
+
+        # cleanup
+        self.env.temp_data.clear()
+        self.env.ref_context.clear()
+
+        self.env.write_doctree(docname, doctree)
+
     def write(self, build_docnames, updated_docnames, method='update'):
         # type: (Iterable[unicode], Sequence[unicode], unicode) -> None
         if build_docnames is None or build_docnames == ['__all__']:

sphinx/environment/__init__.py

@@ -12,7 +12,6 @@
 import os
 import re
 import sys
-import time
 import types
 import warnings
 from collections import defaultdict
@@ -28,12 +27,11 @@ from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warnin
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.errors import SphinxError, ExtensionError
-from sphinx.io import read_doc
 from sphinx.locale import __
 from sphinx.transforms import SphinxTransformer
 from sphinx.util import get_matching_docs, FilenameUniqDict
-from sphinx.util import logging, rst
-from sphinx.util.docutils import sphinx_domains, WarningStream
+from sphinx.util import logging
+from sphinx.util.docutils import WarningStream
 from sphinx.util.i18n import find_catalog_files
 from sphinx.util.matching import compile_matchers
 from sphinx.util.nodes import is_translatable
@@ -555,32 +553,6 @@ class BuildEnvironment(object):
         self.temp_data['default_domain'] = \
             self.domains.get(self.config.primary_domain)
 
-    def read_doc(self, docname, app=None):
-        # type: (unicode, Sphinx) -> None
-        """Parse a file and add/update inventory entries for the doctree."""
-        self.prepare_settings(docname)
-
-        # Add confdir/docutils.conf to dependencies list if exists
-        docutilsconf = path.join(self.app.confdir, 'docutils.conf')
-        if path.isfile(docutilsconf):
-            self.note_dependency(docutilsconf)
-
-        with sphinx_domains(self), rst.default_role(docname, self.config.default_role):
-            doctree = read_doc(self.app, self, self.doc2path(docname))
-
-        # store time of reading, for outdated files detection
-        # (Some filesystems have coarse timestamp resolution;
-        # therefore time.time() can be older than filesystem's timestamp.
-        # For example, FAT32 has 2sec timestamp resolution.)
-        self.all_docs[docname] = max(
-            time.time(), path.getmtime(self.doc2path(docname)))
-
-        # cleanup
-        self.temp_data.clear()
-        self.ref_context.clear()
-
-        self.write_doctree(docname, doctree)
-
     # utilities to use while reading a document
 
     @property
@@ -847,6 +819,12 @@ class BuildEnvironment(object):
                       RemovedInSphinx30Warning)
         return self.app.builder._read_parallel(docnames, nproc)
 
+    def read_doc(self, docname, app=None):
+        # type: (unicode, Sphinx) -> None
+        warnings.warn('env.read_doc() is deprecated. Please use builder.read_doc() instead.',
+                      RemovedInSphinx30Warning)
+        self.app.builder.read_doc(docname)
+
     @property
     def _nitpick_ignore(self):
         # type: () -> List[unicode]