docs: fix of sphinx warnings.

* Fixing [all the warnings](https://gist.github.com/greut/6439ecf10b17b01b125e) given by sphinx during compilation.
* Fixing the PEP8, PyFlakes and PEP257 warnings of the touched files.
* Converting some epydoc to sphinx format.
* Adding some intersphinx.
* Reading the theme from docs/requirements.txt.