DOC/BLD: squash deprecation warnings
DOC: squash even moar warnings
Merge pull request #3725 from cpcloud/sphinx-doc-fixes-3721

DOC/BLD: squash as many doc-build warnings as possible
DOC: readme.rst to reflect changes in install.rst