Doc fixes

1. Fixes `.rst` typos/errors. Sphinx generates docs w/o errors & warnings now. Also fixes dozen of semantic errors in markup, which is "legit" for Sphinx/reST, but breaks markup in resulting HTML.
2. Cosmetic fixes (typography/orpho typos/fixed references).
3. Adds few enhancement to example codeblocks.