Document when sample_default is in use

Because sample_default makes the generator silently ignore the
actual default value, it is possible for it to cause confusion for
users. This change adds a message to the generated opt help to let
them know that the documented default may not be the actual default.

Change-Id: Ib48d5dd1d18546b5464e9e096c47d1e3d67be57c
Closes-Bug: 1795729

oslo_config/generator.py

@@ -321,6 +321,14 @@ class _OptFormatter(object):
                 '# effect on stability and/or performance.\n'
             )
 
+        if opt.sample_default:
+            lines.append(
+                '#\n'
+                '# This option has a sample default set, which means that\n'
+                '# its actual default value may vary from the one documented\n'
+                '# below.\n'
+            )
+
         if hasattr(opt.type, 'format_defaults'):
             defaults = opt.type.format_defaults(opt.default,
                                                 opt.sample_default)

oslo_config/sphinxext.py

@@ -146,6 +146,16 @@ def _format_opt(opt, group_name):
         yield _indent(
             'effect on stability and/or performance.', 6)
 
+    if opt.sample_default:
+        yield _indent(
+            '')
+        yield _indent(
+            'This option has a sample default set, which means that')
+        yield _indent(
+            'its actual default value may vary from the one documented')
+        yield _indent(
+            'above.')
+
     try:
         help_text = opt.help % {'default': 'the value above'}
     except (TypeError, KeyError, ValueError):

oslo_config/tests/test_generator.py

@@ -803,6 +803,10 @@ class GeneratorTestCase(base.BaseTestCase):
 #
 
 # multiple strings (multi valued)
+#
+# This option has a sample default set, which means that
+# its actual default value may vary from the one documented
+# below.
 #multi_opt = 5
 #multi_opt = 6
 ''')),