add detail to driver options in config generator

Have the main _list_opts caller construct the driver option so
individual drivers do not need to repeat that.

Add choices with descriptions when emitting samples. We don't really
care about those for the runtime use, but they improve the output in
the config generator and documentation.

Use an OptGroup with the driver_option and dynamic_group_owner options
set instead of just a group name when describing the options.

Add sample_default values for some of the options in the URI driver.

Change-Id: I14c0a046e6c70a9108308db70a4efb70613d5bb3
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

oslo_config/_list_opts.py

@@ -10,6 +10,8 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+import inspect
+
 from oslo_config import cfg
 
 import stevedore
@@ -37,8 +39,33 @@ def list_opts():
         "oslo.config.driver",
         invoke_on_load=True)
 
-    for driver in ext_mgr.names():
-        options.append(('sample_%s_source' % driver,
-                       ext_mgr[driver].obj.list_options_for_discovery()))
+    source_names = ext_mgr.names()
+    for source_name in source_names:
+        source = ext_mgr[source_name].obj
+        source_options = source.list_options_for_discovery()
+        source_description = inspect.getdoc(source)
+        source_options.insert(
+            0,
+            cfg.StrOpt(
+                name='driver',
+                sample_default=source_name,
+                help=cfg._SOURCE_DRIVER_OPTION_HELP,
+            )
+        )
+        group_name = 'sample_{}_source'.format(source_name)
+        group_help = 'Example of using a {} source'.format(source_name)
+        if source_description:
+            group_help = '{}\n\n{}: {}'.format(
+                group_help,
+                source_name,
+                source_description,
+            )
+        group = cfg.OptGroup(
+            name=group_name,
+            help=group_help,
+            driver_option='driver',
+            dynamic_group_owner='config_source',
+        )
+        options.append((group, source_options))
 
     return options

oslo_config/cfg.py

@@ -507,6 +507,11 @@ import stevedore
 
 LOG = logging.getLogger(__name__)
 
+_SOURCE_DRIVER_OPTION_HELP = (
+    'The name of the driver that can load this '
+    'configuration source.'
+)
+
 
 class Locations(enum.Enum):
     opt_default = (1, False)
@@ -2551,8 +2556,7 @@ class ConfigOpts(collections.Mapping):
         self.register_opt(
             StrOpt('driver',
                    choices=self._ext_mgr.names(),
-                   help=('The name of the driver that can load this '
-                         'configuration source.')),
+                   help=_SOURCE_DRIVER_OPTION_HELP),
             group=group_name)
 
         try:

oslo_config/sources/_uri.py

@@ -40,16 +40,19 @@ class URIConfigurationSourceDriver(sources.ConfigurationSourceDriver):
             'uri',
             schemes=['http', 'https'],
             required=True,
+            sample_default='https://example.com/my-configuration.ini',
             help=('Required option with the URI of the '
                   'extra configuration file\'s location.'),
         ),
         cfg.StrOpt(
             'ca_path',
+            sample_default='/etc/ca-certificates',
             help=('The path to a CA_BUNDLE file or directory '
                   'with certificates of trusted CAs.'),
         ),
         cfg.StrOpt(
             'client_cert',
+            sample_default='/etc/ca-certificates/service-client-keystore',
             help=('Client side certificate, as a single file path '
                   'containing either the certificate only or the '
                   'private key and the certificate.'),
@@ -62,19 +65,7 @@ class URIConfigurationSourceDriver(sources.ConfigurationSourceDriver):
     ]
 
     def list_options_for_discovery(self):
-        # NOTE(moguimar): This option is only used to provide a better
-        #                 description of the driver option registered
-        #                 by ConfigOpts._open_source_from_opt_group().
-        driver_opt = cfg.StrOpt(
-            'driver',
-            default='remote_file',
-            help=('Required option and value for this group to be '
-                  'parsed as an extra source by the URI driver. '
-                  'This group\'s name must be set as one of the '
-                  'config_source\'s values in the [DEFAULT] group.'),
-        )
-
-        return [driver_opt] + self._uri_driver_opts
+        return self._uri_driver_opts
 
     def open_source_from_opt_group(self, conf, group_name):
         conf.register_opts(self._uri_driver_opts, group_name)

oslo_config/tests/test_sources.py

@@ -284,9 +284,10 @@ class URISourceTestCase(base.BaseTestCase):
     def test_list_opts(self):
         expected_group = None
         for group in _list_opts.list_opts():
-            if group[0] == "sample_remote_file_source":
-                expected_group = group
-                break
+            if group[0] is not None:
+                if group[0].name == "sample_remote_file_source":
+                    expected_group = group
+                    break
 
         self.assertIsNotNone(expected_group)