I have just seen a very nice presentation  about writing good documentation. The presenter mentions Sphinx, but also two things I was not aware of:
- documentation hosting site  - I have already registered, but did not
import sfepy there yet, as we do use custom (numpy) sphinx extensions
- pycco  - a literate programming tool.
The talk also stresses that it's primarily the developers who should write the docs, not the (new) users, so I will get better :)