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>