Silence some Sphinx warnings by rewriting docstrings.

Silence some more Sphinx warnings and improving the rendering in some places. This should close #3542