From 90949a3b4fab5b2cd5d2a84980413bbd74d0cc88 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 22 Apr 2018 12:36:52 +0900 Subject: [PATCH 1/2] refactor: Move env.read_doc() to Builder._read_doc() --- CHANGES | 1 + doc/extdev/index.rst | 5 +++++ sphinx/builders/__init__.py | 35 ++++++++++++++++++++++++++++--- sphinx/environment/__init__.py | 38 +++++++--------------------------- 4 files changed, 46 insertions(+), 33 deletions(-) diff --git a/CHANGES b/CHANGES index 1b8645501..f24a82a4b 100644 --- a/CHANGES +++ b/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 `_ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 3a2e7bc25..842f34073 100644 --- a/doc/extdev/index.rst +++ b/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 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index fb171dcde..d5be2a689 100644 --- a/sphinx/builders/__init__.py +++ b/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__']: diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index f69a44d76..f745b81c7 100644 --- a/sphinx/environment/__init__.py +++ b/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] From 39fe7ee29369ce8e0deb815de0dadb561525ddab Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 22 Apr 2018 13:22:42 +0900 Subject: [PATCH 2/2] refactor: Move env.write_doctree() to Builder._write_doctree() --- CHANGES | 1 + doc/extdev/index.rst | 5 +++++ sphinx/builders/__init__.py | 18 +++++++++++++++++- sphinx/environment/__init__.py | 24 ++++++++---------------- 4 files changed, 31 insertions(+), 17 deletions(-) diff --git a/CHANGES b/CHANGES index f24a82a4b..fb965a3d0 100644 --- a/CHANGES +++ b/CHANGES @@ -52,6 +52,7 @@ 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 `_ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 842f34073..2dad3e652 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -218,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 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index d5be2a689..841489704 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -14,6 +14,7 @@ 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 @@ -538,7 +539,22 @@ class Builder(object): self.env.temp_data.clear() self.env.ref_context.clear() - self.env.write_doctree(docname, doctree) + 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 diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index f745b81c7..e8d9dd9d4 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -35,7 +35,7 @@ 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: @@ -655,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 @@ -825,6 +810,13 @@ class BuildEnvironment(object): 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]