sphinxext doesn't handle percentage signs

[Stephen Finucane]

The sphinxext module [1] attempts to allow string substitution for default values in 'Opt.help'. For example:

    cfg.StrOpt('my_opt',
        help='Does something. Defaults to %(default)s')

While I'd question the value of even including this functionality when we could simply print any defaults found separately, it is what it is. However, the feature does break when percentage signs are used and not escaped. For example, the following option from nova [2]:

  cfg.FloatOpt('torrent_seed_chance',
      default=1.0,
      min=0,
      deprecated_for_removal=True,
      deprecated_since='15.0.0',
      deprecated_reason="""
  The torrent feature has not been tested nor maintained, and as such is being
  removed.
  """,
      help='Probability that peer will become a seeder (1.0 = 100%)')

will produce the following traceback:

  Traceback (most recent call last):
    File "setup.py", line 29, in <module>
      pbr=True)
    File "/usr/lib64/python2.7/distutils/core.py", line 151, in setup
      dist.run_commands()
    File "/usr/lib64/python2.7/distutils/dist.py", line 953, in run_commands
      self.run_command(cmd)
    File "/usr/lib64/python2.7/distutils/dist.py", line 972, in run_command
      cmd_obj.run()
    File "/openstack/nova/.eggs/pbr-2.0.0-py2.7.egg/pbr/builddoc.py", line 200, in run
      self._sphinx_run()
  ...
  ...
  ...
    File "/openstack/nova/.tox/docs/lib/python2.7/site-packages/oslo_config/sphinxext.py", line 240, in _format_option_help
      for line in lines:
    File "/openstack/nova/.tox/docs/lib/python2.7/site-packages/oslo_config/sphinxext.py", line 158, in _format_group
      help_text = opt.help % {'default': 'the value above'}
  ValueError: unsupported format character ')' (0x29) at index 54

Given that oslo.config in general doesn't complain about these signs nor attempt any such substitution, we should probably handle this a little more gracefully than we do.

[1] https://github.com/openstack/oslo.config/blob/master/oslo_config/sphinxext.py
[2] https://github.com/openstack/nova/blob/0191fedc/nova/conf/xenserver.py#L174-L183

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/449576

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/449576
Committed: https://git.openstack.org/cgit/openstack/oslo.config/commit/?id=2aba5594d9bd62b5c013f896679f3d4af4163f6c
Submitter: Jenkins
Branch: master

commit 2aba5594d9bd62b5c013f896679f3d4af4163f6c
Author: Stephen Finucane <email address hidden>
Date: Fri Mar 24 11:27:34 2017 +0000

    sphinxext: Handle unescaped percentage signs

    The sphinxext module attempts to allow string substitution for default
    values in 'Opt.help'. This feature breaks when percentage signs are used
    in option help texts and are not escaped. For example, the following
    help text from nova:

        help='Probability that peer will become a seeder (1.0 = 100%)'

    Simply abort the attempt to substitute text in these cases.

    Change-Id: Ia682cd9c91f07fec2faecb4338b777347f774073
    Closes-Bug: #1675737

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/oslo.config 4.0.0 release.