Merge pull request #6419 from larsoner/config

ENH: Explain rebuilds

sphinx/builders/__init__.py

@@ -388,9 +388,11 @@ def read(self) -> List[str]:
  # ... 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 @@ def setup(self, app: "Sphinx") -> None:
  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')