[Python-checkins] r63580 - in doctools/trunk: CHANGES doc/concepts.rst sphinx/roles.py
georg.brandl
python-checkins at python.org
Sat May 24 18:18:55 CEST 2008
Author: georg.brandl
Date: Sat May 24 18:18:54 2008
New Revision: 63580
Log:
#2904: fix :func:`title <target>` behavior.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/concepts.rst
doctools/trunk/sphinx/roles.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sat May 24 18:18:54 2008
@@ -33,6 +33,8 @@
* Use a binary TOC in HTML help generation to fix issues links without
explicit anchors.
+* Fix behavior of references to functions/methods with an explicit title.
+
Release 0.3 (May 6, 2008)
=========================
Modified: doctools/trunk/doc/concepts.rst
==============================================================================
--- doctools/trunk/doc/concepts.rst (original)
+++ doctools/trunk/doc/concepts.rst Sat May 24 18:18:54 2008
@@ -16,10 +16,6 @@
slashes. All values, parameters and suchlike referring to "documents" expect
such a document name.
-.. function:: test()
-
-refer to :func:`test func <test>`.
-
The TOC tree
------------
Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py (original)
+++ doctools/trunk/sphinx/roles.py Sat May 24 18:18:54 2008
@@ -102,9 +102,7 @@
'option': addnodes.literal_emphasis,
}
-def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
- env = inliner.document.settings.env
- text = utils.unescape(text)
+def _fix_parens(typ, text, env):
if typ in ('func', 'meth', 'cfunc'):
if text.endswith('()'):
# remove parentheses
@@ -112,9 +110,14 @@
if env.config.add_function_parentheses:
# add them back to all occurrences if configured
text += '()'
+ return text
+
+def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+ env = inliner.document.settings.env
+ text = utils.unescape(text)
# if the first character is a bang, don't cross-reference at all
if text[0:1] == '!':
- text = text[1:]
+ text = _fix_parens(typ, text[1:], env)
return [innernodetypes.get(typ, nodes.literal)(
rawtext, text, classes=['xref'])], []
# we want a cross-reference, create the reference node
@@ -122,49 +125,55 @@
modname=env.currmodule, classname=env.currclass)
# we may need the line number for warnings
pnode.line = lineno
- innertext = text
- # special actions for Python object cross-references
- if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod'):
- # if the first character is a dot, search more specific namespaces first
- # else search builtins first
- if text[0:1] == '.':
- text = text[1:]
- pnode['refspecific'] = True
- # if the first character is a tilde, don't display the module/class parts
- # of the contents
- elif text[0:1] == '~':
- text = text[1:]
- dot = text.rfind('.')
- if dot != -1:
- innertext = text[dot+1:]
- # look if explicit title and target are given
+ # the link title may differ from the target, but by default they are the same
+ title = target = text
+ titleistarget = True
+ # look if explicit title and target are given with `foo <bar>` syntax
brace = text.find('<')
if brace != -1:
+ titleistarget = False
pnode['refcaption'] = True
m = caption_ref_re.match(text)
if m:
target = m.group(2)
- innertext = m.group(1)
+ title = m.group(1)
else:
# fallback: everything after '<' is the target
target = text[brace+1:]
- innertext = text[:brace]
- # else, generate target from title
- else:
- target = text
- # some special cases
- if typ == 'option' and text[0] in '-/':
+ title = text[:brace]
+ # special target for Python object cross-references
+ if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod'):
+ # fix-up parentheses in link title
+ if titleistarget:
+ title = _fix_parens(typ, title.lstrip('.~'), env)
+ # remove parentheses from the target too
+ if target.endswith('()'):
+ target = target[:-2]
+ # if the first character is a dot, search more specific namespaces first
+ # else search builtins first
+ if target[0:1] == '.':
+ target = target[1:]
+ pnode['refspecific'] = True
+ # if the first character is a tilde, don't display the module/class parts
+ # of the contents
+ elif target[0:1] == '~':
+ target = target[1:]
+ dot = target.rfind('.')
+ if dot != -1:
+ title = target[dot+1:]
+ # some other special cases for the target
+ elif typ == 'option' and target[0] in '-/':
# strip option marker from target
target = target[1:]
- if typ == 'term':
+ elif typ == 'term':
# normalize whitespace in definition terms (if the term reference is
- # broken over a line, a newline will be in text)
+ # broken over a line, a newline will be in target)
target = ws_re.sub(' ', target).lower()
else:
# 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'])
+ pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, classes=['xref'])
return [pnode], []
More information about the Python-checkins
mailing list