Update documentation

This pr updates the traits source doc-strings so that they can be picked up by sphinx extensions and reworks theirs
appearance.