Check out my https://github.com/dave/rebecca package for a neat way of building readme docs by embedding Go docs and examples.

It generates the big readme for https://github.com/dave/jennifer (see https://github.com/dave/jennifer/blob/master/README.md.tpl).