replace python docs with Go example tests

I cleaned up the docs according to the godoc formatting rules and removed python annotations.

I translated the code examples to Go and put them in example_test.go for better formatting in godoc.