Updates formatting on doc recently moved from wiki

This PR closes issue #1283.

Changes to Restructured text to clean up file.
"Then we could write a corresponding test in" ?