classification
Title: sphinx.doc.autodoc: Hook for changing argspec
Type: enhancement Stage:
Components: Documentation tools (Sphinx) Versions: 3rd party
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, pv
Priority: normal Keywords: patch

Created on 2008-07-20 23:08 by pv, last changed 2008-07-29 18:53 by pv. This issue is now closed.

Files
File name Uploaded Description Edit
autodoc-process-signature.patch pv, 2008-07-24 21:11 Add autodoc-process-signature signal to sphinx.ext.autodoc
Messages (4)
msg70096 - (view) Author: Pauli Virtanen (pv) * Date: 2008-07-20 23:08
It would be useful if the 

    autodoc-process-docstring

event from sphinx.ext.autodoc allowed to change the argspec of the 
function being documented. Some other hook for changing the function 
signature would also do.

We are using Sphinx for generating a reference guide for Numpy, where 
many of the functions are from extension modules for which 
inspect.getargspec does not work. Instead, the function signature is 
contained within the object's docstring. Right now I'm simply 
monkeypatching sphinx.ext.autodoc.format_signature, but a cleaner 
approach would be better.

It seems that this would be fairly easy to implement in generate_rst. 
Perhaps a .signature attribute to the Options passed to the hook would 
be an acceptable solution?

I can write a patch doing this, if someone doesn't do this faster.
msg70226 - (view) Author: Pauli Virtanen (pv) * Date: 2008-07-24 21:11
Suggested patch attached. Tested on Numpy documentation.

It adds a new signal,

    autodoc-process-signature(app, what, name, obj, options,
                              signature, return_annotation)

which is assumed to return either None or a 
new (signature, return_annotation) tuple. Warnings are raised
only if introspection fails and none of the event handlers returns
a new signature.
msg70408 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-07-29 18:31
Thanks, committed the patch with a few changes in r65290. Let me know if
it works!
msg70410 - (view) Author: Pauli Virtanen (pv) * Date: 2008-07-29 18:53
Thanks, works OK.
History
Date User Action Args
2008-07-29 18:53:43pvsetmessages: + msg70410
2008-07-29 18:31:02georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg70408
2008-07-24 21:11:08pvsetfiles: + autodoc-process-signature.patch
keywords: + patch
messages: + msg70226
2008-07-20 23:08:34pvcreate