Merge pull request #4880 from tk0miya/refactor_env2

Refactor BuildEnvironment: Move read_doc() method to Builder class

CHANGES

@@ -51,6 +51,8 @@ Deprecated
 * ``Config.check_unicode()`` is deprecated
 * ``sphinx.application.CONFIG_FILENAME`` is deprecated
 * ``highlightlang`` directive is deprecated
+* ``env.read_doc()`` is deprecated
+* ``env.write_doctree()`` 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
@@ -213,6 +218,11 @@ The following is a list of deprecated interface.
      - 3.0
      - ``Builder.read()``
 
+   * - ``BuildEnvironment.write_doctree()``
+     - 1.8
+     - 3.0
+     - ``Builder.write_doctree()``
+
    * - ``sphinx.locale.l_()``
      - 1.8
      - 3.0

sphinx/builders/__init__.py

@@ -9,19 +9,23 @@
     :license: BSD, see LICENSE for details.
 """
 
+import time
 import warnings
 from os import path
 
 from docutils import nodes
+from six.moves import cPickle as pickle
 
 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 +482,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 +495,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 +515,47 @@ 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.write_doctree(docname, doctree)
+
+    def write_doctree(self, docname, doctree):
+        # type: (unicode, nodes.Node) -> None
+        """Write the doctree to a file."""
+        # make it picklable
+        doctree.reporter = None
+        doctree.transformer = None
+        doctree.settings.warning_stream = None
+        doctree.settings.env = None
+        doctree.settings.record_dependencies = None
+
+        doctree_filename = self.env.doc2path(docname, self.env.doctreedir, '.doctree')
+        ensuredir(path.dirname(doctree_filename))
+        with open(doctree_filename, 'wb') as f:
+            pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
+
     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,16 +27,15 @@ 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
-from sphinx.util.osutil import SEP, ensuredir, relpath
+from sphinx.util.osutil import SEP, relpath
 from sphinx.util.websupport import is_commentable
 
 if False:
@@ -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
@@ -683,21 +655,6 @@ class BuildEnvironment(object):
         doctree.reporter = Reporter(self.doc2path(docname), 2, 5, stream=WarningStream())
         return doctree
 
-    def write_doctree(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
-        """Write the doctree to a file."""
-        # make it picklable
-        doctree.reporter = None
-        doctree.transformer = None
-        doctree.settings.warning_stream = None
-        doctree.settings.env = None
-        doctree.settings.record_dependencies = None
-
-        doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree')
-        ensuredir(path.dirname(doctree_filename))
-        with open(doctree_filename, 'wb') as f:
-            pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
-
     def get_and_resolve_doctree(self, docname, builder, doctree=None,
                                 prune_toctrees=True, includehidden=False):
         # type: (unicode, Builder, nodes.Node, bool, bool) -> nodes.Node
@@ -847,6 +804,19 @@ 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)
+
+    def write_doctree(self, docname, doctree):
+        # type: (unicode, nodes.Node) -> None
+        warnings.warn('env.write_doctree() is deprecated. '
+                      'Please use builder.write_doctree() instead.',
+                      RemovedInSphinx30Warning)
+        self.app.builder.write_doctree(docname, doctree)
+
     @property
     def _nitpick_ignore(self):
         # type: () -> List[unicode]