[rfc] rework doc structure for signals

Create issue
Issue #1086 resolved
Tay Ray Chuan created an issue

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.

Comments (2)

  1. Log in to comment