sphinxext: Correct issues with usage formatting

There are two issues here stemming from required options:

- If the option contains a hyphen, e.g. '--required-option', then it is
  split into multiple tokens
- The arguments for these options are not surrounded by triangular
  brackets like optional options are, but these are expected

Correct both issues.

Change-Id: Ifc20e6936a9ce4ef4f22b2c17298d6ca552640f7

cliff/sphinxext.py

@@ -56,11 +56,11 @@ def _format_usage(parser):
 
     # hacked variant of the regex used by the actual argparse module. Unlike
     # that version, this one attempts to group long and short opts with their
-    # optional arguments ensuring that, for example, '---format <FORMAT>'
+    # optional arguments ensuring that, for example, '--format <FORMAT>'
     # becomes ['--format <FORMAT>'] and not ['--format', '<FORMAT>'].
     # Yes, they really do use regexes to break apart and rewrap their help
     # string. Don't ask me why.
-    part_regexp = r'\(.*?\)+|\[.*?\]+|(?:(?:-\w|--\w+)(?:\s+<\w+>)?)|\S+'
+    part_regexp = r'\(.*?\)+|\[.*?\]+|(?:(?:-\w|--[\w-]+)(?:\s+<?\w+>?)?)|\S+'
 
     opt_usage = fmt._format_actions_usage(optionals, groups)
     pos_usage = fmt._format_actions_usage(positionals, groups)

cliff/tests/test_sphinxext.py

@@ -157,6 +157,8 @@ class TestSphinxExtension(base.TestBase):
         parser.add_argument('--write-to-var-log-something-or-other',
                             action='store_true',
                             help='a long opt to force wrapping')
+        parser.add_argument('--required-arg', dest='stuff', required=True,
+                            help='a required argument')
         style_group = parser.add_mutually_exclusive_group(required=True)
         style_group.add_argument('--polite', action='store_true',
                                  help='use a polite greeting')
@@ -172,6 +174,7 @@ class TestSphinxExtension(base.TestBase):
                 [--language LANG]
                 [--translate]
                 [--write-to-var-log-something-or-other]
+                --required-arg STUFF
                 (--polite | --profane)
                 name
 
@@ -187,6 +190,10 @@ class TestSphinxExtension(base.TestBase):
 
             a long opt to force wrapping
 
+        .. option:: --required-arg <STUFF>
+
+            a required argument
+
         .. option:: --polite
 
             use a polite greeting