I think I got most of the formatting problems in this round.  There
are a few places where blank lines could be added; for technical
reasons I'd prefer to leave that tidying to followup patches.

I didn't do anything about python style/portability issues yet, or
integrate the new docs completely into the notmuch build system.

To test you need sphinx >= v1.0 or rst2man from docutils (not sure of version)

% make man # sphinx based, ends up in doc/_build/man

% make rst2man # ends up in doc/rst2man

Currently the latter ends in a man hierarchy, the former not. Not sure
if this matters.