diff --git a/CHANGES b/CHANGES index 73380f9cb..3a9e86953 100644 --- a/CHANGES +++ b/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. diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst index 64f2f1c04..ce6269799 100644 --- a/doc/markup/desc.rst +++ b/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 + .. cmdoption:: -m , --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. diff --git a/sphinx/directives.py b/sphinx/directives.py index 8195cc988..6d8a34290 100644 --- a/sphinx/directives.py +++ b/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 - prefix, optname, args = m.groups() - signode += addnodes.desc_name(prefix+optname, prefix+optname) - signode += addnodes.desc_classname(args, args) - return optname + 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) + if not count: + firstname = optname + count += 1 + if not firstname: + raise ValueError + return firstname def desc_directive(desctype, arguments, options, content, lineno, diff --git a/sphinx/roles.py b/sphinx/roles.py index d9927165e..a9f200c34 100644 --- a/sphinx/roles.py +++ b/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': + 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(' ', text).lower() - elif typ == 'option': - # strip option marker from target - if text[0] in '-/': - target = text[1:] - else: - target = 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], []