Strip parentheses during conversion, add them during build.

converter/newfiles/conf.py

@@ -37,5 +37,5 @@ last_updated_format = '%b %d, %Y'
 # typographically correct entities.
 use_smartypants = True
 
-# If true, trailing '()' will be stripped from :func: etc. cross-references.
-strip_trailing_parentheses = False
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True

converter/newfiles/doc_sphinx.rst

@@ -50,6 +50,6 @@ use_smartypants : bool
    If true, use SmartyPants to convert quotes and dashes to the typographically
    correct entities.
 
-strip_trailing_parentheses : bool
-   If true, trailing parentheses will be stripped from ``:func:`` etc.
-   crossreferences.
+add_function_parentheses : bool
+   If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
+   ``:cfunc:`` cross-references.

converter/util.py

@@ -70,6 +70,7 @@ wordchars_s = alphanum + u'_.-'
 wordchars_e = alphanum + u'+`(-'
 bad_markup_re = re.compile(r'(:[a-zA-Z0-9_-]+:)?(`{1,2})[ ]*(.+?)[ ]*(\2)')
 quoted_code_re = re.compile(r'\\`(``.+?``)\'')
+paren_re = re.compile(r':(func|meth|cfunc):`(.*?)\(\)`')
 
 def repair_bad_inline_markup(text):
     # remove quoting from `\code{x}'
@@ -80,6 +81,9 @@ def repair_bad_inline_markup(text):
     # special: literal backquotes
     xtext = xtext.replace('``````', '\x02')
 
+    # remove () from function markup
+    xtext = paren_re.sub(r':\1:`\2`', xtext)
+
     ntext = []
     lasti = 0
     l = len(xtext)

sphinx/roles.py

@@ -98,9 +98,9 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     # 'token' is the default role inside 'productionlist' directives
     if typ == '':
         typ = 'token'
-    if env.config.get('strip_trailing_parentheses', False):
-        if text[-2:] == '()':
-            text = text[:-2]
+    if typ in ('func', 'meth', 'cfunc') and \
+           env.config.get('add_function_parentheses', True):
+        text += '()'
     pnode = addnodes.pending_xref(rawtext)
     pnode['reftype'] = typ
     pnode['reftarget'] = ws_re.sub('', text)