[#1022] Fix cross-references in API docstrings

Use :py:func:, :py:class: etc to do proper hyperlinked cross-references.

Also a few other minor docstrings formatting fixes.
Merge branch '1022-api-docs-improvements'