Fix :term:title <target>, and make giving multiple cmdoptions possible.

CHANGES

@@ -10,6 +10,11 @@ Changes in trunk
 * sphinx.directives: Allow giving a different title to documents
   in the toctree.
 
+* sphinx.directives: Allow giving multiple options in a ``cmdoption``
+  directive.
+
+* sphinx.roles: Fix referencing glossary terms with explicit targets.
+
 * sphinx.builder, sphinx.environment: Gracefully handle some exception
   cases.
 

doc/markup/desc.rst

@@ -175,15 +175,19 @@ The directives are:
    Describes a Python bytecode instruction (this is not very useful for projects
    other than Python itself).
 
-.. directive:: .. cmdoption:: name args
+.. directive:: .. cmdoption:: name args, name args, ...
 
    Describes a command line option or switch.  Option argument names should be
    enclosed in angle brackets.  Example::
 
-      .. cmdoption:: -m <module>
+      .. cmdoption:: -m <module>, --module <module>
 
          Run a module as a script.
 
+   The directive will create a cross-reference target named after the *first*
+   option, referencable by :role:`option` (in the example case, you'd use
+   something like ``:option:`-m```).
+
 .. directive:: .. envvar:: name
 
    Describes an environment variable that the documented code uses or defines.

sphinx/directives.py

@@ -272,16 +272,24 @@ def parse_opcode_signature(signode, sig):
     return opname.strip()
 
 
-option_desc_re = re.compile(r'([-/])([-_a-zA-Z0-9]+)(\s*.*)')
+option_desc_re = re.compile(r'(/|-|--)([-_a-zA-Z0-9]+)(\s*.*?)(?=,|$)')
 
 def parse_option_desc(signode, sig):
     """Transform an option description into RST nodes."""
-    m = option_desc_re.match(sig)
-    if m is None: raise ValueError
+    count = 0
+    firstname = ''
+    for m in option_desc_re.finditer(sig):
         prefix, optname, args = m.groups()
+        if count:
+            signode += addnodes.desc_classname(', ', ', ')
         signode += addnodes.desc_name(prefix+optname, prefix+optname)
         signode += addnodes.desc_classname(args, args)
-    return optname
+        if not count:
+            firstname = optname
+        count += 1
+    if not firstname:
+        raise ValueError
+    return firstname
 
 
 def desc_directive(desctype, arguments, options, content, lineno,

sphinx/roles.py

@@ -150,18 +150,19 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
             target = text[brace+1:]
             innertext = text[:brace]
     # else, generate target from title
-    elif typ == 'term':
-        # normalize whitespace in definition terms (if the term reference is
-        # broken over a line, a newline will be in text)
-        target = ws_re.sub(' ', text).lower()
-    elif typ == 'option':
-        # strip option marker from target
-        if text[0] in '-/':
-            target = text[1:]
     else:
         target = text
+    # some special cases
+    if typ == 'option' and text[0] in '-/':
+        # strip option marker from target
+        target = target[1:]
+    if typ == 'term':
+        # normalize whitespace in definition terms (if the term reference is
+        # broken over a line, a newline will be in text)
+        target = ws_re.sub(' ', target).lower()
     else:
-        target = ws_re.sub('', text)
+        # remove all whitespace to avoid referencing problems
+        target = ws_re.sub('', target)
     pnode['reftarget'] = target
     pnode += innernodetypes.get(typ, nodes.literal)(rawtext, innertext, classes=['xref'])
     return [pnode], []