trying to fix pdf generation, attempt 11

the function diff had a return followed by rtype and raises
this may be the cause of the nested too deeply error.

now decided not to document exception raises as this appears to cause the issue

fixed a lot of formatting issues by this point