docs: fix of sphinx warnings.

* Fixing all the warnings given by sphinx during compilation.

* Fixing the PEP8, PyFlakes and PEP257 warnings of the touched files.

* Adding some intersphinx.

* Reading the theme from docs/requirements.txt.

Signed-off-by: Yoan Blanc <yoan.blanc@cern.ch>