ENH: Explain rebuilds

sphinx/builders/__init__.py

@@ -388,9 +388,11 @@ class Builder:
             # ... but not those that already were removed
             changed.update(self.env.glob_toctrees & self.env.found_docs)
 
-        if changed:
-            reason = CONFIG_CHANGED_REASON.get(self.env.config_status, '')
+        if updated:  # explain the change iff build config status was not ok
+            reason = (CONFIG_CHANGED_REASON.get(self.env.config_status, '') +
+                      (self.env.config_status_extra or ''))
             logger.info('[%s] ', reason, nonl=True)
+
         logger.info(__('%s added, %s changed, %s removed'),
                     len(added), len(changed), len(removed))
 

sphinx/environment/__init__.py

@@ -95,14 +95,15 @@ class BuildEnvironment:
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app: "Sphinx" = None):
-        self.app = None             # type: Sphinx
-        self.doctreedir = None      # type: str
-        self.srcdir = None          # type: str
-        self.config = None          # type: Config
-        self.config_status = None   # type: int
-        self.events = None          # type: EventManager
-        self.project = None         # type: Project
-        self.version = None         # type: Dict[str, str]
+        self.app = None                  # type: Sphinx
+        self.doctreedir = None           # type: str
+        self.srcdir = None               # type: str
+        self.config = None               # type: Config
+        self.config_status = None        # type: int
+        self.config_status_extra = None  # type: str
+        self.events = None               # type: EventManager
+        self.project = None              # type: Project
+        self.version = None              # type: Dict[str, str]
 
         # the method of doctree versioning; see set_versioning_method
         self.versioning_condition = None  # type: Union[bool, Callable]
@@ -232,16 +233,25 @@ class BuildEnvironment:
     def _update_config(self, config: Config) -> None:
         """Update configurations by new one."""
         self.config_status = CONFIG_OK
+        self.config_status_extra = ''
         if self.config is None:
             self.config_status = CONFIG_NEW
         elif self.config.extensions != config.extensions:
             self.config_status = CONFIG_EXTENSIONS_CHANGED
+            extensions = sorted(
+                set(self.config.extensions) ^ set(config.extensions))
+            if len(extensions) == 1:
+                extension = extensions[0]
+            else:
+                extension = '%d' % (len(extensions),)
+            self.config_status_extra = ' (%r)' % (extension,)
         else:
             # check if a config value was changed that affects how
             # doctrees are read
             for item in config.filter('env'):
                 if self.config[item.name] != item.value:
                     self.config_status = CONFIG_CHANGED
+                    self.config_status_extra = ' (%r)' % (item.name,)
                     break
 
         self.config = config

tests/test_environment.py

@@ -7,6 +7,8 @@
     :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+import os
+import shutil
 import pytest
 
 from sphinx.builders.html import StandaloneHTMLBuilder
@@ -23,18 +25,30 @@ def test_config_status(make_app, app_params):
     app1 = make_app(*args, freshenv=True, **kwargs)
     assert app1.env.config_status == CONFIG_NEW
     app1.build()
+    assert '[new config] 1 added' in app1._status.getvalue()
 
     # incremental build (no config changed)
     app2 = make_app(*args, **kwargs)
     assert app2.env.config_status == CONFIG_OK
+    app2.build()
+    assert "0 added, 0 changed, 0 removed" in app2._status.getvalue()
 
     # incremental build (config entry changed)
-    app3 = make_app(*args, confoverrides={'master_doc': 'content'}, **kwargs)
+    app3 = make_app(*args, confoverrides={'master_doc': 'indexx'}, **kwargs)
+    fname = os.path.join(app3.srcdir, 'index.rst')
+    assert os.path.isfile(fname)
+    shutil.move(fname, fname[:-4] + 'x.rst')
     assert app3.env.config_status == CONFIG_CHANGED
+    app3.build()
+    shutil.move(fname[:-4] + 'x.rst', fname)
+    assert "[config changed ('master_doc')] 1 added" in app3._status.getvalue()
 
     # incremental build (extension changed)
     app4 = make_app(*args, confoverrides={'extensions': ['sphinx.ext.autodoc']}, **kwargs)
     assert app4.env.config_status == CONFIG_EXTENSIONS_CHANGED
+    app4.build()
+    want_str = "[extensions changed ('sphinx.ext.autodoc')] 1 added"
+    assert want_str in app4._status.getvalue()
 
 
 @pytest.mark.sphinx('dummy')