Hello phoku,
I honestly think you should head over to the PEP008 first.
That's where most of our guidelines were inspired from.
I know the PEP8, but were to lazy to shorten it to one document

As a documentation generator we use epydoc, another great tool is sphinx.
Django uses it - and well it's docs are awesome(1).
It's hard to disagree that sphinx documentation is great but it requires learning Yet Another Markup Languge (RST in this case) apart from Wiki syntax

Because ATM most of interfaces are written in C++ we use doxygen. I dont have idea how to document Python wrappers, maybe you can share some thoughts?
Good luck with your project :-)
Thanks, FIFE and PyChan are success stories and encourage me to work on project

I hope that i'll find some time for FIFE development too in near future.