Consider standardising doc-strings to ReadTheDocs

[julianstirling]

Our doc-strings in the Python code are currently pretty ad hoc. We can make far better code documentation if we use standardised formatting such as that used by ReadTheDocs.