use admonitions
fix various local refs
use definition lists for options
minor sphinx formatting change
Merge pull request #303 from sa2ajj/docs-fixes

Docs fixes