fix up documentation, ensure doctests run cleanly