In autodoc, allow customizing the signature of an object via autodoc-process-signature where the built-in mechanism fails.

CHANGES

@@ -1,6 +1,9 @@
 Release 0.6.5 (in development)
 ==============================
 
+* In autodoc, allow customizing the signature of an object where
+  the built-in mechanism fails.
+
 * #331: Fix output for enumerated lists with start values in LaTeX.
 
 * Make the ``start-after`` and ``end-before`` options to the

sphinx/ext/autodoc.py

@@ -365,9 +365,13 @@ class Documenter(object):
             args = "(%s)" % self.args
         else:
             # try to introspect the signature
-            args = self.format_args()
-        if args is None:
-            return ''
+            try:
+                args = self.format_args()
+            except Exception, err:
+                self.directive.warn('error while formatting arguments for '
+                                    '%s: %s' % (self.fullname, err))
+                args = None
+
         retann = self.retann
 
         result = self.env.app.emit_firstresult(
@@ -644,12 +648,7 @@ class Documenter(object):
         self.add_line(u'', '')
 
         # format the object's signature, if any
-        try:
-            sig = self.format_signature()
-        except Exception, err:
-            self.directive.warn('error while formatting signature for '
-                                '%s: %s' % (self.fullname, err))
-            sig = ''
+        sig = self.format_signature()
 
         # generate the directive header and options, if applicable
         self.add_directive_header(sig)
@@ -849,7 +848,6 @@ class ClassDocumenter(ModuleLevelDocumenter):
         return ret
 
     def format_args(self):
-        args = None
         # for classes, the relevant signature is the __init__ method's
         initmeth = self.get_attr(self.object, '__init__', None)
         # classes without __init__ method, default __init__ or

tests/test_autodoc.py

@@ -169,8 +169,9 @@ def test_format_signature():
     assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)'
     assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)'
 
-    # test exception handling
-    raises(TypeError, formatsig, 'function', 'int', int, None, None)
+    # test exception handling (exception is caught and args is '')
+    assert formatsig('function', 'int', int, None, None) == ''
+    del _warnings[:]
 
     # test processing by event handler
     assert formatsig('method', 'bar', H.foo1, None, None) == '42'