示例#1
0
def _format_group(app, namespace, group_name, group_obj, opt_list):
    group_name = group_name or 'DEFAULT'
    app.info('[oslo.config] %s %s' % (namespace, group_name))

    yield '.. oslo.config:group:: %s' % group_name
    if namespace:
        yield '   :namespace: %s' % namespace
    yield ''

    if group_obj and group_obj.help:
        yield _indent(group_obj.help.rstrip())
        yield ''

    for opt in opt_list:
        opt_type = _TYPE_DESCRIPTIONS.get(type(opt), 'unknown type')
        yield '.. oslo.config:option:: %s' % opt.dest
        yield ''
        yield _indent(':Type: %s' % opt_type)
        for default in generator._format_defaults(opt):
            if default:
                default = '``' + default + '``'
            yield _indent(':Default: %s' % default)
        if getattr(opt.type, 'min', None) is not None:
            yield _indent(':Minimum Value: %s' % opt.type.min)
        if getattr(opt.type, 'max', None) is not None:
            yield _indent(':Maximum Value: %s' % opt.type.max)
        if getattr(opt.type, 'choices', None):
            choices_text = ', '.join(
                [_get_choice_text(choice) for choice in opt.type.choices])
            yield _indent(':Valid Values: %s' % choices_text)
        try:
            if opt.mutable:
                yield _indent(
                    ':Mutable: This option can be changed without restarting.',
                )
        except AttributeError as err:
            # NOTE(dhellmann): keystoneauth defines its own Opt class,
            # and neutron (at least) returns instances of those
            # classes instead of oslo_config Opt instances. The new
            # mutable attribute is the first property where the API
            # isn't supported in the external class, so we can use
            # this failure to emit a warning. See
            # https://bugs.launchpad.net/keystoneauth/+bug/1548433 for
            # more details.
            import warnings
            if not isinstance(cfg.Opt, opt):
                warnings.warn(
                    'Incompatible option class for %s (%r): %s' %
                    (opt.dest, opt.__class__, err), )
            else:
                warnings.warn('Failed to fully format sample for %s: %s' %
                              (opt.dest, err))
        yield ''

        try:
            help_text = opt.help % {'default': 'the value above'}
        except (TypeError, KeyError):
            # There is no mention of the default in the help string,
            # or the string had some unknown key
            help_text = opt.help
        if help_text:
            yield _indent(help_text)
            yield ''

        if opt.deprecated_opts:
            for line in _list_table(
                ['Group', 'Name'],
                ((d.group or 'DEFAULT', d.name or opt.dest or 'UNSET')
                 for d in opt.deprecated_opts),
                    title='Deprecated Variations'):
                yield _indent(line)
        if opt.deprecated_for_removal:
            yield _indent('.. warning::')
            yield _indent('   This option is deprecated for removal.')
            yield _indent('   Its value may be silently ignored ')
            yield _indent('   in the future.')
            yield ''
            if opt.deprecated_reason:
                yield _indent('   :Reason: ' + opt.deprecated_reason)
            yield ''

        yield ''
示例#2
0
    def run(self):
        env = self.state.document.settings.env
        app = env.app

        namespace = ' '.join(self.content)

        opts = generator._list_opts([namespace])

        result = ViewList()
        source_name = '<' + __name__ + '>'

        def _add(text):
            "Append some text to the output result view to be parsed."
            result.append(text, source_name)

        def _add_indented(text):
            """Append some text, indented by a couple of spaces.

            Indent everything under the option name,
            to format it as a definition list.
            """
            _add(_indent(text))

        by_section = {}

        for ignore, opt_list in opts:
            for group_name, opts in opt_list:
                by_section.setdefault(group_name, []).extend(opts)

        for group_name, opt_list in sorted(by_section.items()):
            group_name = group_name or 'DEFAULT'
            app.info('[oslo.config] %s %s' % (namespace, group_name))
            _add(group_name)
            _add('=' * len(group_name))
            _add('')

            for opt in opt_list:
                opt_type = self._TYPE_DESCRIPTIONS.get(type(opt),
                                                       'unknown type')
                _add('``%s``' % opt.dest)
                _add('')
                _add_indented(':Type: %s' % opt_type)
                for default in generator._format_defaults(opt):
                    if default:
                        default = '``' + default + '``'
                    _add_indented(':Default: %s' % default)
                if getattr(opt.type, 'min', None):
                    _add_indented(':Minimum Value: %s' % opt.type.min)
                if getattr(opt.type, 'max', None):
                    _add_indented(':Maximum Value: %s' % opt.type.max)
                if getattr(opt.type, 'choices', None):
                    choices_text = ', '.join([
                        self._get_choice_text(choice)
                        for choice in opt.type.choices
                    ])
                    _add_indented(':Valid Values: %s' % choices_text)
                _add('')

                _add_indented(opt.help)
                _add('')

                if opt.deprecated_opts:
                    _list_table(
                        _add_indented,
                        ['Group', 'Name'],
                        ((d.group or 'DEFAULT', d.name or opt.dest or 'UNSET')
                         for d in opt.deprecated_opts),
                        title='Deprecated Variations',
                    )
                if opt.deprecated_for_removal:
                    _add_indented('.. warning:')
                    _add_indented('   This option is deprecated for removal.')
                    _add_indented('   Its value may be silently ignored ')
                    _add_indented('   in the future.')
                    _add('')

                _add('')

        node = nodes.section()
        node.document = self.state.document
        nested_parse_with_titles(self.state, result, node)

        return node.children
示例#3
0
def _format_group(app, namespace, group_name, group_obj, opt_list):
    group_name = group_name or 'DEFAULT'
    app.info('[oslo.config] %s %s' % (namespace, group_name))

    yield '.. oslo.config:group:: %s' % group_name
    if namespace:
        yield '   :namespace: %s' % namespace
    yield ''

    if group_obj and group_obj.help:
        yield _indent(group_obj.help.rstrip())
        yield ''

    for opt in opt_list:
        opt_type = _TYPE_DESCRIPTIONS.get(type(opt),
                                          'unknown type')
        yield '.. oslo.config:option:: %s' % opt.dest
        yield ''
        yield _indent(':Type: %s' % opt_type)
        for default in generator._format_defaults(opt):
            if default:
                default = '``' + default + '``'
            yield _indent(':Default: %s' % default)
        if getattr(opt.type, 'min', None) is not None:
            yield _indent(':Minimum Value: %s' % opt.type.min)
        if getattr(opt.type, 'max', None) is not None:
            yield _indent(':Maximum Value: %s' % opt.type.max)
        if getattr(opt.type, 'choices', None):
            choices_text = ', '.join([_get_choice_text(choice)
                                      for choice in opt.type.choices])
            yield _indent(':Valid Values: %s' % choices_text)
        try:
            if opt.mutable:
                yield _indent(
                    ':Mutable: This option can be changed without restarting.',
                )
        except AttributeError as err:
            # NOTE(dhellmann): keystoneauth defines its own Opt class,
            # and neutron (at least) returns instances of those
            # classes instead of oslo_config Opt instances. The new
            # mutable attribute is the first property where the API
            # isn't supported in the external class, so we can use
            # this failure to emit a warning. See
            # https://bugs.launchpad.net/keystoneauth/+bug/1548433 for
            # more details.
            import warnings
            if not isinstance(cfg.Opt, opt):
                warnings.warn(
                    'Incompatible option class for %s (%r): %s' %
                    (opt.dest, opt.__class__, err),
                )
            else:
                warnings.warn('Failed to fully format sample for %s: %s' %
                              (opt.dest, err))
        yield ''

        try:
            help_text = opt.help % {'default': 'the value above'}
        except (TypeError, KeyError):
            # There is no mention of the default in the help string,
            # or the string had some unknown key
            help_text = opt.help
        if help_text:
            yield _indent(help_text)
            yield ''

        if opt.deprecated_opts:
            for line in _list_table(
                    ['Group', 'Name'],
                    ((d.group or 'DEFAULT',
                      d.name or opt.dest or 'UNSET')
                     for d in opt.deprecated_opts),
                    title='Deprecated Variations'):
                yield _indent(line)
        if opt.deprecated_for_removal:
            yield _indent('.. warning::')
            yield _indent('   This option is deprecated for removal.')
            yield _indent('   Its value may be silently ignored ')
            yield _indent('   in the future.')
            yield ''
            if opt.deprecated_reason:
                yield _indent('   :Reason: ' + opt.deprecated_reason)
            yield ''

        yield ''
示例#4
0
def _format_opt(opt, group_name):
    opt_type = _TYPE_DESCRIPTIONS.get(type(opt), 'unknown type')
    yield '.. oslo.config:option:: %s' % opt.dest
    yield ''
    yield _indent(':Type: %s' % opt_type)
    for default in generator._format_defaults(opt):
        if default:
            yield _indent(':Default: ``%s``' % default)
        else:
            yield _indent(':Default: ``%r``' % default)
    if getattr(opt.type, 'min', None) is not None:
        yield _indent(':Minimum Value: %s' % opt.type.min)
    if getattr(opt.type, 'max', None) is not None:
        yield _indent(':Maximum Value: %s' % opt.type.max)
    if getattr(opt.type, 'choices', None):
        choices_text = ', '.join(
            [_get_choice_text(choice) for choice in opt.type.choices])
        yield _indent(':Valid Values: %s' % choices_text)
    try:
        if opt.mutable:
            yield _indent(
                ':Mutable: This option can be changed without restarting.')
    except AttributeError as err:
        # NOTE(dhellmann): keystoneauth defines its own Opt class,
        # and neutron (at least) returns instances of those
        # classes instead of oslo_config Opt instances. The new
        # mutable attribute is the first property where the API
        # isn't supported in the external class, so we can use
        # this failure to emit a warning. See
        # https://bugs.launchpad.net/keystoneauth/+bug/1548433 for
        # more details.
        import warnings
        if not isinstance(cfg.Opt, opt):
            warnings.warn(
                'Incompatible option class for %s (%r): %s' %
                (opt.dest, opt.__class__, err), )
        else:
            warnings.warn('Failed to fully format sample for %s: %s' %
                          (opt.dest, err))
    if opt.advanced:
        yield _indent(
            ':Advanced Option: Intended for advanced users and not used')
        yield _indent('by the majority of users, and might have a significant',
                      6)
        yield _indent('effect on stability and/or performance.', 6)

    try:
        help_text = opt.help % {'default': 'the value above'}
    except (TypeError, KeyError, ValueError):
        # There is no mention of the default in the help string,
        # the string had some unknown key, or the string contained
        # invalid formatting characters
        help_text = opt.help
    if help_text:
        yield ''
        for line in help_text.strip().splitlines():
            yield _indent(line.rstrip())

    # We don't bother outputting this if not using new-style choices with
    # inline descriptions
    if getattr(opt.type, 'choices',
               None) and not all(x is None for x in opt.type.choices.values()):
        yield ''
        yield _indent('.. rubric:: Possible values')
        for choice in opt.type.choices:
            yield ''
            yield _indent(_get_choice_text(choice))
            yield _indent(
                _indent(opt.type.choices[choice]
                        or '<No description provided>'))

    if opt.deprecated_opts:
        yield ''
        for line in _list_table(
            ['Group', 'Name'],
            ((d.group or group_name, d.name or opt.dest or 'UNSET')
             for d in opt.deprecated_opts),
                title='Deprecated Variations'):
            yield _indent(line)

    if opt.deprecated_for_removal:
        yield ''
        yield _indent('.. warning::')
        if opt.deprecated_since:
            yield _indent('   This option is deprecated for removal '
                          'since %s.' % opt.deprecated_since)
        else:
            yield _indent('   This option is deprecated for removal.')
        yield _indent('   Its value may be silently ignored ')
        yield _indent('   in the future.')
        if opt.deprecated_reason:
            reason = ' '.join(
                [x.strip() for x in opt.deprecated_reason.splitlines()])
            yield ''
            yield _indent('   :Reason: ' + reason)

    yield ''
示例#5
0
def _format_opt(opt, group_name):
    opt_type = _TYPE_DESCRIPTIONS.get(type(opt),
                                      'unknown type')
    yield '.. oslo.config:option:: %s' % opt.dest
    yield ''
    yield _indent(':Type: %s' % opt_type)
    for default in generator._format_defaults(opt):
        if default:
            yield _indent(':Default: ``%s``' % default)
        else:
            yield _indent(':Default: ``%r``' % default)
    if getattr(opt.type, 'min', None) is not None:
        yield _indent(':Minimum Value: %s' % opt.type.min)
    if getattr(opt.type, 'max', None) is not None:
        yield _indent(':Maximum Value: %s' % opt.type.max)
    if getattr(opt.type, 'choices', None):
        choices_text = ', '.join([_get_choice_text(choice)
                                  for choice in opt.type.choices])
        yield _indent(':Valid Values: %s' % choices_text)
    try:
        if opt.mutable:
            yield _indent(
                ':Mutable: This option can be changed without restarting.'
            )
    except AttributeError as err:
        # NOTE(dhellmann): keystoneauth defines its own Opt class,
        # and neutron (at least) returns instances of those
        # classes instead of oslo_config Opt instances. The new
        # mutable attribute is the first property where the API
        # isn't supported in the external class, so we can use
        # this failure to emit a warning. See
        # https://bugs.launchpad.net/keystoneauth/+bug/1548433 for
        # more details.
        import warnings
        if not isinstance(cfg.Opt, opt):
            warnings.warn(
                'Incompatible option class for %s (%r): %s' %
                (opt.dest, opt.__class__, err),
            )
        else:
            warnings.warn('Failed to fully format sample for %s: %s' %
                          (opt.dest, err))
    if opt.advanced:
        yield _indent(
            ':Advanced Option: Intended for advanced users and not used')
        yield _indent(
            'by the majority of users, and might have a significant', 6)
        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):
        # There is no mention of the default in the help string,
        # the string had some unknown key, or the string contained
        # invalid formatting characters
        help_text = opt.help
    if help_text:
        yield ''
        for line in help_text.strip().splitlines():
            yield _indent(line.rstrip())

    # We don't bother outputting this if not using new-style choices with
    # inline descriptions
    if getattr(opt.type, 'choices', None) and not all(
            x is None for x in opt.type.choices.values()):
        yield ''
        yield _indent('.. rubric:: Possible values')
        for choice in opt.type.choices:
            yield ''
            yield _indent(_get_choice_text(choice))
            yield _indent(_indent(
                opt.type.choices[choice] or '<No description provided>'))

    if opt.deprecated_opts:
        yield ''
        for line in _list_table(
                ['Group', 'Name'],
                ((d.group or group_name,
                  d.name or opt.dest or 'UNSET')
                 for d in opt.deprecated_opts),
                title='Deprecated Variations'):
            yield _indent(line)

    if opt.deprecated_for_removal:
        yield ''
        yield _indent('.. warning::')
        if opt.deprecated_since:
            yield _indent('   This option is deprecated for removal '
                          'since %s.' % opt.deprecated_since)
        else:
            yield _indent('   This option is deprecated for removal.')
        yield _indent('   Its value may be silently ignored ')
        yield _indent('   in the future.')
        if opt.deprecated_reason:
            reason = ' '.join([x.strip() for x in
                               opt.deprecated_reason.splitlines()])
            yield ''
            yield _indent('   :Reason: ' + reason)

    yield ''
    def format(self, opt, group_name, namespace, minimal=False, summarize=False):
        """Format a description of an option to the output file.

        :param opt: a cfg.Opt instance
        :param group_name: name of the group to which the opt is assigned
        :param minimal: enable option by default, marking it as required
        :param summarize: output a summarized description of the opt
        :returns: a formatted opt description string
        """

        if hasattr(opt.type, 'format_defaults'):
            defaults = opt.type.format_defaults(opt.default,
                                                opt.sample_default)
        else:
            LOG.debug(
                "The type for option %(name)s which is %(type)s is not a "
                "subclass of types.ConfigType and doesn't provide a "
                "'format_defaults' method. A default formatter is not "
                "available so the best-effort formatter will be used.",
                {'type': opt.type, 'name': opt.name})
            defaults = _format_defaults(opt)
        lines=[]
        # line = '{{ $x := dict "empty" "dict'
        for default_str in defaults:

            # alanmeadows(NOTE)
            # 
            # avert your eyes, I got lazy.
            
            if len(group_name.split('.')) > 1:  

                line = '{{- if not .%s -}}{{- set . "%s" dict -}}{{- end -}}\n' % (group_name.lower().split('.')[0], group_name.lower().split('.')[0])

                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

                line = '{{- if not .%s.%s -}}{{- set .%s "%s" dict -}}{{- end -}}\n' % (group_name.lower().split('.')[0], 
                                                                                  group_name.lower().split('.')[1],
                                                                                  group_name.lower().split('.')[0],
                                                                                  group_name.lower().split('.')[1])
                
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            else:

                line = '{{- if not .%s -}}{{- set . "%s" dict -}}{{- end -}}\n' % (group_name.lower(), group_name.lower())
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            if len(namespace.split('.')) == 1:                
                line = '{{- if not .%s.%s -}}{{- set .%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), namespace, group_name.lower(), namespace)
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            if len(namespace.split('.')) > 1:  

                line = '{{- if not .%s.%s -}}{{- set .%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), namespace.split('.')[0], group_name.lower(), namespace.split('.')[0])
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

                line = '{{- if not .%s.%s.%s -}}{{- set .%s.%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), \
                                                                                       namespace.split('.')[0], \
                                                                                       namespace.split('.')[1], \
                                                                                       group_name.lower(), \
                                                                                       namespace.split('.')[0], \
                                                                                       namespace.split('.')[1])
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            if len(namespace.split('.')) > 2:  
                line = '{{- if not .%s.%s.%s.%s -}}{{- set .%s.%s.%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), \
                                                                                            namespace.split('.')[0], \
                                                                                            namespace.split('.')[1], \
                                                                                            namespace.split('.')[2], \
                                                                                            group_name.lower(), \
                                                                                            namespace.split('.')[0], \
                                                                                            namespace.split('.')[1], \
                                                                                            namespace.split('.')[2])
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            if len(opt.dest.split('.')) > 1:
                line = '{{- if not .%s.%s.%s -}}{{- set .%s.%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), \
                                                                                        namespace, \
                                                                                        opt.dest.split('.')[0], \
                                                                                        group_name.lower(), \
                                                                                        namespace, \
                                                                                        opt.dest.split('.')[0])
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

            if len(opt.dest.split('.')) > 2:
                line = '{{- if not .%s.%s.%s.%s -}}{{- set .%s.%s.%s "%s" dict -}}{{- end -}}\n' % (group_name.lower(), \
                                                                                              namespace, \
                                                                                              opt.dest.split('.')[0], \
                                                                                              opt.dest.split('.')[1], \
                                                                                              group_name.lower(), \
                                                                                              namespace, \
                                                                                              opt.dest.split('.')[0], \
                                                                                              opt.dest.split('.')[1])
                if line not in self.done:
                    self.done.append(line)
                    lines.append(line)

        if lines:
            self.writelines(lines)
示例#7
0
    def run(self):
        env = self.state.document.settings.env
        app = env.app

        namespace = ' '.join(self.content)

        opts = generator._list_opts([namespace])

        result = ViewList()
        source_name = '<' + __name__ + '>'

        def _add(text):
            "Append some text to the output result view to be parsed."
            result.append(text, source_name)

        def _add_indented(text):
            """Append some text, indented by a couple of spaces.

            Indent everything under the option name,
            to format it as a definition list.
            """
            _add(_indent(text))

        by_section = {}

        for ignore, opt_list in opts:
            for group_name, opts in opt_list:
                by_section.setdefault(group_name, []).extend(opts)

        for group_name, opt_list in sorted(by_section.items()):
            group_name = group_name or 'DEFAULT'
            app.info('[oslo.config] %s %s' % (namespace, group_name))

            _add('.. oslo.config:group:: %s' % group_name)
            _add('')

            for opt in opt_list:
                opt_type = self._TYPE_DESCRIPTIONS.get(type(opt),
                                                       'unknown type')
                _add('.. oslo.config:option:: %s' % opt.dest)
                _add('')
                _add_indented(':Type: %s' % opt_type)
                for default in generator._format_defaults(opt):
                    if default:
                        default = '``' + default + '``'
                    _add_indented(':Default: %s' % default)
                if getattr(opt.type, 'min', None):
                    _add_indented(':Minimum Value: %s' % opt.type.min)
                if getattr(opt.type, 'max', None):
                    _add_indented(':Maximum Value: %s' % opt.type.max)
                if getattr(opt.type, 'choices', None):
                    choices_text = ', '.join([self._get_choice_text(choice)
                                              for choice in opt.type.choices])
                    _add_indented(':Valid Values: %s' % choices_text)
                _add('')

                try:
                    help_text = opt.help % {'default': 'the value above'}
                except TypeError:
                    # There is no mention of the default in the help string.
                    help_text = opt.help
                _add_indented(help_text)
                _add('')

                if opt.deprecated_opts:
                    _list_table(
                        _add_indented,
                        ['Group', 'Name'],
                        ((d.group or 'DEFAULT',
                          d.name or opt.dest or 'UNSET')
                         for d in opt.deprecated_opts),
                        title='Deprecated Variations',
                    )
                if opt.deprecated_for_removal:
                    _add_indented('.. warning::')
                    _add_indented('   This option is deprecated for removal.')
                    _add_indented('   Its value may be silently ignored ')
                    _add_indented('   in the future.')
                    if opt.deprecated_reason:
                        _add_indented('   Reason: ' + opt.deprecated_reason)
                    _add('')

                _add('')

        node = nodes.section()
        node.document = self.state.document
        nested_parse_with_titles(self.state, result, node)

        return node.children
    def format(self,
               opt,
               group_name,
               namespace,
               minimal=False,
               summarize=False):
        """Format a description of an option to the output file.

        :param opt: a cfg.Opt instance
        :param group_name: name of the group to which the opt is assigned
        :param minimal: enable option by default, marking it as required
        :param summarize: output a summarized description of the opt
        :returns: a formatted opt description string
        """
        if not opt.help:
            LOG.warning(_LW('"%s" is missing a help string'), opt.dest)

        opt_type = _format_type_name(opt.type)
        opt_prefix = ''
        if (opt.deprecated_for_removal
                and not opt.help.startswith('DEPRECATED')):
            opt_prefix = 'DEPRECATED: '

        if opt.help:
            # an empty line signifies a new paragraph. We only want the
            # summary line
            if summarize:
                _split = opt.help.split('\n\n')
                opt_help = _split[0].rstrip(':').rstrip('.')
                if len(_split) > 1:
                    opt_help += '. For more information, refer to the '
                    opt_help += 'documentation.'
            else:
                opt_help = opt.help

            help_text = u'%s%s (%s)' % (opt_prefix, opt_help, opt_type)
        else:
            help_text = u'(%s)' % opt_type
        lines = self._format_help(help_text)

        if getattr(opt.type, 'min', None) is not None:
            lines.append('# Minimum value: %d\n' % opt.type.min)

        if getattr(opt.type, 'max', None) is not None:
            lines.append('# Maximum value: %d\n' % opt.type.max)

        if getattr(opt.type, 'choices', None):
            choices_text = ', '.join(
                [self._get_choice_text(choice) for choice in opt.type.choices])
            lines.append('# Allowed values: %s\n' % choices_text)

        try:
            if opt.mutable:
                lines.append(
                    '# Note: This option can be changed without restarting.\n')
        except AttributeError as err:
            # NOTE(dhellmann): keystoneauth defines its own Opt class,
            # and neutron (at least) returns instances of those
            # classes instead of oslo_config Opt instances. The new
            # mutable attribute is the first property where the API
            # isn't supported in the external class, so we can use
            # this failure to emit a warning. See
            # https://bugs.launchpad.net/keystoneauth/+bug/1548433 for
            # more details.
            import warnings
            if not isinstance(opt, cfg.Opt):
                warnings.warn(
                    'Incompatible option class for %s (%r): %s' %
                    (opt.dest, opt.__class__, err), )
            else:
                warnings.warn('Failed to fully format sample for %s: %s' %
                              (opt.dest, err))

        for d in opt.deprecated_opts:
            lines.append('# Deprecated group/name - [%s]/%s\n' %
                         (d.group or group_name, d.name or opt.dest))

        if opt.deprecated_for_removal:
            if opt.deprecated_since:
                lines.append(
                    '# This option is deprecated for removal since %s.\n' %
                    (opt.deprecated_since))
            else:
                lines.append('# This option is deprecated for removal.\n')
            lines.append(
                '# Its value may be silently ignored in the future.\n')
            if opt.deprecated_reason:
                lines.extend(
                    self._format_help('Reason: ' + opt.deprecated_reason))

        if opt.advanced:
            lines.append(
                '# Advanced Option: intended for advanced users and not used\n'
                '# by the majority of users, and might have a significant\n'
                '# effect on stability and/or performance.\n')

        if hasattr(opt.type, 'format_defaults'):
            defaults = opt.type.format_defaults(opt.default,
                                                opt.sample_default)
        else:
            LOG.debug(
                "The type for option %(name)s which is %(type)s is not a "
                "subclass of types.ConfigType and doesn't provide a "
                "'format_defaults' method. A default formatter is not "
                "available so the best-effort formatter will be used.", {
                    'type': opt.type,
                    'name': opt.name
                })
            defaults = _format_defaults(opt)
        for default_str in defaults:
            if type(opt) in [cfg.MultiOpt, cfg.MultiStrOpt]:
                lines.append('# from .%s.%s.%s (multiopt)\n' %
                             (group_name.lower(), namespace, opt.dest))
                lines.append(
                    '{{ if not .%s.%s.%s }}#%s = '
                    '{{ .%s.%s.%s | default "%s" }}{{ else }}'
                    '{{ range .%s.%s.%s }}%s = {{ . }}{{ end }}'
                    '{{ end }}\n' %
                    (group_name.lower(), namespace, opt.dest, opt.dest,
                     group_name.lower(), namespace, opt.dest,
                     default_str.replace('"', r'\"'), group_name.lower(),
                     namespace, opt.dest, opt.dest))

            else:
                lines.append('# from .%s.%s.%s\n' %
                             (group_name.lower(), namespace, opt.dest))
                if minimal:
                    lines.append('%s = {{ .%s.%s.%s | default "%s" }}\n' %
                                 (opt.dest, group_name.lower(), namespace,
                                  opt.dest, default_str.replace('"', r'\"')))
                else:
                    lines.append('{{ if not .%s.%s.%s }}#{{ end }}%s = '
                                 '{{ .%s.%s.%s | default "%s" }}\n' %
                                 (group_name.lower(), namespace, opt.dest,
                                  opt.dest, group_name.lower(), namespace,
                                  opt.dest, default_str.replace('"', r'\"')))

        self.writelines(lines)
示例#9
0
def _format_group(app, namespace, group_name, group_obj, opt_list):
    group_name = group_name or 'DEFAULT'
    app.info('[oslo.config] %s %s' % (namespace, group_name))

    yield '.. oslo.config:group:: %s' % group_name
    if namespace:
        yield '   :namespace: %s' % namespace
    yield ''

    if group_obj and group_obj.help:
        yield _indent(group_obj.help.rstrip())
        yield ''

    for opt in opt_list:
        opt_type = _TYPE_DESCRIPTIONS.get(type(opt),
                                          'unknown type')
        yield '.. oslo.config:option:: %s' % opt.dest
        yield ''
        yield _indent(':Type: %s' % opt_type)
        for default in generator._format_defaults(opt):
            if default:
                default = '``' + default + '``'
            yield _indent(':Default: %s' % default)
        if getattr(opt.type, 'min', None) is not None:
            yield _indent(':Minimum Value: %s' % opt.type.min)
        if getattr(opt.type, 'max', None) is not None:
            yield _indent(':Maximum Value: %s' % opt.type.max)
        if getattr(opt.type, 'choices', None):
            choices_text = ', '.join([_get_choice_text(choice)
                                      for choice in opt.type.choices])
            yield _indent(':Valid Values: %s' % choices_text)
        yield ''

        try:
            help_text = opt.help % {'default': 'the value above'}
        except (TypeError, KeyError):
            # There is no mention of the default in the help string,
            # or the string had some unknown key
            help_text = opt.help
        if help_text:
            yield _indent(help_text)
            yield ''

        if opt.deprecated_opts:
            for line in _list_table(
                    ['Group', 'Name'],
                    ((d.group or 'DEFAULT',
                      d.name or opt.dest or 'UNSET')
                     for d in opt.deprecated_opts),
                    title='Deprecated Variations'):
                yield _indent(line)
        if opt.deprecated_for_removal:
            yield _indent('.. warning::')
            yield _indent('   This option is deprecated for removal.')
            yield _indent('   Its value may be silently ignored ')
            yield _indent('   in the future.')
            yield ''
            if opt.deprecated_reason:
                yield _indent('   :Reason: ' + opt.deprecated_reason)
            yield ''

        yield ''