ENH: added some links to relevant documentation
ENH: added more annotation of output
ENH: added check for h5py, fixes #1596
DOC: modernized the upgrade instructions