DOC: fix several Sphinx warnings when building the docs

patch developed with Dmitrijs Milajevs and Ioannis Tziakos