Improve warning message when a section contains unused options.

This fixes #483

news/483.feature

@@ -0,0 +1 @@
+Improve warning message when a section contains unused options. (#483)

src/zc/buildout/buildout.py

@@ -2010,8 +2010,11 @@ def _check_for_unused_options_in_section(buildout, section):
     unused = [option for option in sorted(options._raw)
               if option not in options._data]
     if unused:
-        buildout._logger.warning("Unused options for %s: %s."
-                                 % (section, ' '.join(map(repr, unused)))
+        buildout._logger.warning(
+            "Section `%s` contains unused option(s): %s.\n"
+            "This may be an indication for either a typo in the option's name "
+            "or a bug in the used recipe." %
+            (section, ' '.join(map(repr, unused)))
         )
 
 _usage = """\

src/zc/buildout/tests/allowhosts.txt

@@ -114,7 +114,8 @@ https://bugs.launchpad.net/zc.buildout/+bug/239212::
     ... ''')
     >>> print_('XX'); print_(system(buildout), end='') # doctest: +ELLIPSIS
     X...
-    Unused options for buildout: 'foo'.
+    Section `buildout` contains unused option(s): 'foo'.
+    This may be an indication for either a typo in the option's name or a bug in the used recipe.
     Installing python...
     Generated interpreter '/sample-buildout/bin/python'.
 

src/zc/buildout/tests/extends-cache.txt

@@ -49,7 +49,8 @@ Error: Couldn't download 'http://localhost/base.cfg' in offline mode.
 Trying the same online, we can:
 
 >>> print_(system(buildout))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 As long as we haven't said anything about caching downloaded configuration,
 nothing gets cached. Offline mode will still cause the buildout to fail:
@@ -74,7 +75,8 @@ being a hash of the complete URL):
 ... """ % server_url)
 
 >>> print_(system(buildout))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 >>> cache = join(sample_buildout, 'cache')
 >>> ls(cache)
@@ -89,7 +91,8 @@ foo = bar
 We can now run buildout offline as it will read base.cfg from the cache:
 
 >>> print_(system(buildout + ' -o'))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 The cache is being used purely as a fall-back in case we are offline or don't
 have access to a configuration file to be downloaded. As long as we are
@@ -105,23 +108,27 @@ base.cfg from the cache:
 ... """)
 
 >>> print_(system(buildout + ' -o'))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 .. verify same behavior for install-from-cache:
 
    >>> print_(system(buildout + ' install-from-cache=true download-cache=.'))
-   Unused options for buildout: 'foo'.
+   Section `buildout` contains unused option(s): 'foo'.
+   This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 In online mode, buildout will download and use the modified version:
 
 >>> print_(system(buildout))
-Unused options for buildout: 'bar'.
+Section `buildout` contains unused option(s): 'bar'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 Trying offline mode again, the new version will be used as it has been put in
 the cache now:
 
 >>> print_(system(buildout + ' -o'))
-Unused options for buildout: 'bar'.
+Section `buildout` contains unused option(s): 'bar'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 Clean up:
 
@@ -212,7 +219,8 @@ Buildout will now assemble its configuration from all of these 6 files,
 defaults first. The online resources end up in the respective extends caches:
 
 >>> print_(system(buildout))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 >>> ls('user-cache')
 -  10e772cf422123ef6c64ae770f555740
@@ -258,7 +266,8 @@ Let's rewrite the config files, clean out the caches and re-run buildout:
 >>> remove('cache', os.listdir('cache')[0])
 
 >>> print_(system(buildout))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 >>> ls('user-cache')
 -  0548bad6002359532de37385bb532e26
@@ -336,7 +345,8 @@ Error: Couldn't download 'http://localhost/base.cfg' in offline mode.
 ... offline = true
 ... """ % server_url)
 >>> print_(system(buildout))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 The ``install-from-cache`` option is treated accordingly:
 
@@ -429,7 +439,8 @@ A change to ``base.cfg`` is picked up on the next buildout run:
 ... foo = bar
 ... """)
 >>> print_(system(buildout + " -n"))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 >>> cat('cache', os.listdir(cache)[0])
 [buildout]
 parts =
@@ -443,7 +454,8 @@ already present in the extends cache will not be updated:
 ... parts =
 ... """)
 >>> print_(system(buildout + " -N"))
-Unused options for buildout: 'foo'.
+Section `buildout` contains unused option(s): 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 >>> cat('cache', os.listdir(cache)[0])
 [buildout]
 parts =
@@ -472,7 +484,8 @@ used:
 ... extends = %sbaseA.cfg %sbaseB.cfg
 ... """ % (server_url, server_url))
 >>> print_(system(buildout + " -n"))
-Unused options for buildout: 'bar' 'foo'.
+Section `buildout` contains unused option(s): 'bar' 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 (XXX We patch download utility's API to produce readable output for the test;
 a better solution would re-use the logging already done by the utility.)
@@ -489,7 +502,8 @@ The URL http://localhost/baseA.cfg was downloaded.
 The URL http://localhost/base.cfg was downloaded.
 The URL http://localhost/baseB.cfg was downloaded.
 Not upgrading because not running a local buildout command.
-Unused options for buildout: 'bar' 'foo'.
+Section `buildout` contains unused option(s): 'bar' 'foo'.
+This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
 >>> zc.buildout.download.Download.download = old_download
 

src/zc/buildout/tests/test_all.py

@@ -822,7 +822,8 @@ def bug_92891_bootstrap_crashes_with_egg_recipe_in_buildout_section():
     Generated script '/sample-bootstrap/bin/buildout'.
 
     >>> print_(system(os.path.join('bin', 'buildout')), end='')
-    Unused options for buildout: 'scripts' 'eggs'.
+    Section `buildout` contains unused option(s): 'eggs' 'scripts'.
+    This may be an indication for either a typo in the option's name or a bug in the used recipe.
 
     """
 
@@ -1659,9 +1660,11 @@ def whine_about_unused_options():
 
     >>> print_(system(buildout), end='')
     Develop: '/sample-buildout/.'
-    Unused options for buildout: 'a'.
+    Section `buildout` contains unused option(s): 'a'.
+    This may be an indication for either a typo in the option's name or a bug in the used recipe.
     Installing foo.
-    Unused options for foo: 'z'.
+    Section `foo` contains unused option(s): 'z'.
+    This may be an indication for either a typo in the option's name or a bug in the used recipe.
     '''
 
 def abnormal_exit():

src/zc/buildout/tests/update.txt

@@ -196,7 +196,8 @@ directory:
     Restarting.
     Generated script '/sample-buildout/bin/buildout'.
     Develop: '/sample-buildout/showversions'
-    Unused options for buildout: 'relative-paths'.
+    Section `buildout` contains unused option(s): 'relative-paths'.
+    This may be an indication for either a typo in the option's name or a bug in the used recipe.
     Updating show-versions.
     zc.buildout 99.99