Improvements to docs formatting.
Merge pull request #4220 from takluyver/docs-shotgun-1

Various improvements to docs formatting

Clearing up some of the broken formatting in the docs, in no particular order.