Fix docstrings

I spent some time fixing up the docstrings.

The first tranche of commits does fairly minimal fixing that worked OK for me when I was testing - in the sense I got no LaTeX errors. 

The latter commits are an idea I had to generalize what I thought you were trying to do with the docstring templates.  It's a little frameworkey - but it seemed to make the code a little more readable - to me.

Feel free to discard the later commits if they are not attractive.

You'll also see in one of the first commit messages that I ran into trouble running the ``rdirective`` sphinx extension and had to disable it.  It wasn't obvious to me what the fix was, I was hoping it was more obvious to you.