diff options
| author | Ben Nemec <bnemec@redhat.com> | 2018-10-02 19:30:06 +0000 |
|---|---|---|
| committer | Ben Nemec <bnemec@redhat.com> | 2018-10-02 19:30:06 +0000 |
| commit | 8cc60344e6e0ad96edeaeb2f41eca129f87ffbcf (patch) | |
| tree | fa48fb51994256dd6ba6937a4be385079ceb4782 | |
| parent | 7072a7552dcb58a60d08c73c1d002fdf1c5a6202 (diff) | |
| download | oslo-config-8cc60344e6e0ad96edeaeb2f41eca129f87ffbcf.tar.gz | |
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
| -rw-r--r-- | oslo_config/generator.py | 8 | ||||
| -rw-r--r-- | oslo_config/sphinxext.py | 10 | ||||
| -rw-r--r-- | oslo_config/tests/test_generator.py | 4 |
3 files changed, 22 insertions, 0 deletions
diff --git a/oslo_config/generator.py b/oslo_config/generator.py index 7b6e5ad..1c1017f 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 0026931..00fdd03 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 c966b40..a7c5f4a 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 ''')), |