[Python-checkins] r62202 - in doctools/trunk: CHANGES doc/markup/desc.rst sphinx/directives.py sphinx/roles.py
georg.brandl
python-checkins at python.org
Mon Apr 7 07:19:27 CEST 2008
Author: georg.brandl
Date: Mon Apr 7 07:19:26 2008
New Revision: 62202
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/markup/desc.rst
doctools/trunk/sphinx/directives.py
doctools/trunk/sphinx/roles.py
Log:
Fix :term:`title <target>`, and make giving multiple cmdoptions possible.
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Mon Apr 7 07:19:26 2008
@@ -10,6 +10,11 @@
* 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.
Modified: doctools/trunk/doc/markup/desc.rst
==============================================================================
--- doctools/trunk/doc/markup/desc.rst (original)
+++ doctools/trunk/doc/markup/desc.rst Mon Apr 7 07:19:26 2008
@@ -175,15 +175,19 @@
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.
Modified: doctools/trunk/sphinx/directives.py
==============================================================================
--- doctools/trunk/sphinx/directives.py (original)
+++ doctools/trunk/sphinx/directives.py Mon Apr 7 07:19:26 2008
@@ -272,16 +272,24 @@
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,
Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py (original)
+++ doctools/trunk/sphinx/roles.py Mon Apr 7 07:19:26 2008
@@ -150,18 +150,19 @@
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], []
More information about the Python-checkins
mailing list