Api docs and updates to handling of __version__

replaces previous pull request, removing create-or-update issue which needs more discussion.