Examples: refactor and documentation

[mrcook]

When looking over the examples I was struggling to understand it all, so I pulled the examples out into a separate project and started refactoring them to help me better understand. I also started adding a bunch of notes.

I thought maybe other people would find this useful so I decided to turn it into a proper effort and make it available for others.

https://github.com/mrcook/go-plugin-examples

The main changes are:

• Expand README and add Makefile for easier execution
• Make each example completely standalone
• Renamed many things, including shared package to sdk, binary names, etc.
• Standardise naming and across all examples
• Replace ENVs with CLI args
• Document a fair chunk of the code

If you'd like me to create a PR from this I'd be more than happy to do so. If not, please go ahead and close this issue.

Cheers,
Michael

[2rs2ts]

@mrcook Thanks for making that repo! I took a look at it before filing #249 because I thought perhaps you had cracked the code on why the protoc generation command doesn't work, but you seemed to be using the same exact command as this repo does. Does your example repo not suffer from the same problem that I had in #249? If not, then could you explain how you fixed it? That'd be a huge help for me, if not for the hashicorp devs too.

[mrcook]

Hi @2rs2ts, as perhaps you guessed already, this was also broken for me...I just hadn't got around to updating that part. I see from your PR that you figured things out, still, you motivated me into fixing my repo, which has now been updated. Cheers!

P.S. I'm not sure if the python plugin actually works, and at the moment I have no desire to learn enough python to check that.

[2rs2ts]

@mrcook It worked IME but it requires installing a bunch of pip deps that just weren't stated at all in the docs. I can't even remember anymore which things I had to install, and which things we installed uselessly, but I only documented it in part in #250 because I felt like maybe there was something about not saying what deps needed to be installed that was considered normal. Like maybe people who are used to gRPC development with Python and Golang both just don't need to be told something like that, and it would come across as unnecessary fluff... but I did at least document the main stuff we needed to get it to work, so please feel free to check out my fork's branch to see if you can make any use of it.