From 8cc60344e6e0ad96edeaeb2f41eca129f87ffbcf Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Tue, 2 Oct 2018 19:30:06 +0000
Subject: [PATCH] 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            |  8 ++++++++
 oslo_config/sphinxext.py            | 10 ++++++++++
 oslo_config/tests/test_generator.py |  4 ++++
 3 files changed, 22 insertions(+)

diff --git a/oslo_config/generator.py b/oslo_config/generator.py
index 7b6e5ad4..1c1017f3 100644
--- a/oslo_config/generator.py
+++ b/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)
diff --git a/oslo_config/sphinxext.py b/oslo_config/sphinxext.py
index 00269310..00fdd038 100644
--- a/oslo_config/sphinxext.py
+++ b/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):
diff --git a/oslo_config/tests/test_generator.py b/oslo_config/tests/test_generator.py
index c966b40f..a7c5f4a3 100644
--- a/oslo_config/tests/test_generator.py
+++ b/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
 ''')),