I've published this as [[http://bitbucket.org/rctay/satchmo/changeset/247aee0453a5/ | r1611:247aee0453a5]] in my fork.
From my commit message (can't figure out how to do block quotes):
Move doc into the signal definition in the python file - this makes it easy for developers who wish to hook onto signals to easily learn of the arguments a listener may accept.
Add arguments into function signature; they are structured such that listeners can be defined easily by copy-pasting the signature.
While we're at it, use field lists for arguments.
Also, use arg instead of
arg, as sphinx' doc does (and we already do so elsewhere).
Note: We can't use the usual docstring, since signals aren't methods/ functions/classes - instead we must use '#:' comments.