Merge pull request #4625 from tk0miya/add_app.phase

Add app.phase to let components know the current build phase

sphinx/application.py

@@ -40,6 +40,7 @@ from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import import_object
 from sphinx.util import logging
 from sphinx.util import pycompat  # noqa: F401
+from sphinx.util.build_phase import BuildPhase
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.docutils import is_html5_writer_available, directive_helper
 from sphinx.util.i18n import find_catalog_source_files
@@ -126,6 +127,7 @@ class Sphinx(object):
                  freshenv=False, warningiserror=False, tags=None, verbosity=0,
                  parallel=0):
         # type: (unicode, unicode, unicode, unicode, unicode, Dict, IO, IO, bool, bool, List[unicode], int, int) -> None  # NOQA
+        self.phase = BuildPhase.INITIALIZATION
         self.verbosity = verbosity
         self.extensions = {}                    # type: Dict[unicode, Extension]
         self._setting_up_extension = ['?']      # type: List[unicode]
@@ -332,6 +334,7 @@ class Sphinx(object):
 
     def build(self, force_all=False, filenames=None):
         # type: (bool, List[unicode]) -> None
+        self.phase = BuildPhase.READING
         try:
             if force_all:
                 self.builder.compile_all_catalogs()

sphinx/builders/__init__.py

@@ -18,6 +18,7 @@ from docutils import nodes
 from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.util import i18n, import_object, logging, status_iterator
+from sphinx.util.build_phase import BuildPhase
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.i18n import find_catalog
 from sphinx.util.osutil import SEP, ensuredir, relative_uri
@@ -365,6 +366,7 @@ class Builder(object):
             logger.info('done')
 
             # global actions
+            self.app.phase = BuildPhase.CONSISTENCY_CHECK
             logger.info(bold('checking consistency... '), nonl=True)
             self.env.check_consistency()
             logger.info('done')
@@ -373,6 +375,8 @@ class Builder(object):
                 logger.info(bold('no targets are out of date.'))
                 return
 
+        self.app.phase = BuildPhase.RESOLVING
+
         # filter "docnames" (list of outdated files) by the updated
         # found_docs of the environment; this will remove docs that
         # have since been removed
@@ -437,7 +441,9 @@ class Builder(object):
         with logging.pending_warnings():
             for docname in status_iterator(docnames, 'writing output... ', "darkgreen",
                                            len(docnames), self.app.verbosity):
+                self.app.phase = BuildPhase.RESOLVING
                 doctree = self.env.get_and_resolve_doctree(docname, self)
+                self.app.phase = BuildPhase.WRITING
                 self.write_doc_serialized(docname, doctree)
                 self.write_doc(docname, doctree)
 
@@ -445,18 +451,22 @@ class Builder(object):
         # type: (Sequence[unicode], int) -> None
         def write_process(docs):
             # type: (List[Tuple[unicode, nodes.Node]]) -> None
+            self.app.phase = BuildPhase.WRITING
             for docname, doctree in docs:
                 self.write_doc(docname, doctree)
 
         # warm up caches/compile templates using the first document
         firstname, docnames = docnames[0], docnames[1:]
+        self.app.phase = BuildPhase.RESOLVING
         doctree = self.env.get_and_resolve_doctree(firstname, self)
+        self.app.phase = BuildPhase.WRITING
         self.write_doc_serialized(firstname, doctree)
         self.write_doc(firstname, doctree)
 
         tasks = ParallelTasks(nproc)
         chunks = make_chunks(docnames, nproc)
 
+        self.app.phase = BuildPhase.RESOLVING
         for chunk in status_iterator(chunks, 'writing output... ', "darkgreen",
                                      len(chunks), self.app.verbosity):
             arg = []

sphinx/util/build_phase.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.util.build_phase
+    ~~~~~~~~~~~~~~~~~~~~~~~
+
+    Build phase of Sphinx application.
+
+    :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+try:
+    from enum import IntEnum
+except ImportError:  # py27
+    IntEnum = object  # type: ignore
+
+
+class BuildPhase(IntEnum):
+    """Build phase of Sphinx application."""
+    INITIALIZATION = 1
+    READING = 2
+    CONSISTENCY_CHECK = 3
+    RESOLVING = 3
+    WRITING = 4