Address warnings in documentation build

[petergtz]

Right now, the documentation build spits out hundreds of warnings. Those warnings make it extremely difficult to see real issues. Unfortunately, missing real issues during Sphinx builds, means certain pages will simply not be created, or certain parts of pages are left out silently.

By systematically resolving and fixing the warnings, we should be able to better see when there's a real issue.