DOC: silence several Sphinx warnings when building the docs

Fixes some twenty-odd Sphinx errors/warnings, mostly typos, unshielded markup (*, | etc), and complaints about duplicate references. The latter seem to be related to the fact that numpydoc mangles the numeric references, but not abbreviations, so that eg `[1]_` gets a unique number, but `[CT]_` does not.

No attempt is made at `document not included in any toctree` warnings of https://github.com/scipy/scipy/pull/3893

Done with @dimazest and @itziakos during the Bloomberg hackathon last Sunday.
@dimazest you have more fixes in your fork, correct?
 


The `~` has to operations:
1. The reference to the class object will show only `orthopoly1d`
2. Sphinx will try to match `.orthopoly1d` when looking for the right target to in the index of classes to link against.