CI: Automated check that examples in docs/examples work

[pmengelbert]

When the spec changes, we should have an automated check that the examples in docs/examples aren't out of date. This can probably be conditional on changes to the spec.go file.

[DannyBrito]

Do you mind expanding what were you thinking to accomplish here? When would this check happened? during a PR, merge, cron event? What would be the actions to take if examples are outdated? Open an issue about updating examples? Block PR if using that event and have author also change examples before merging?

[pmengelbert]

I think it should happen on every PR. What we want to accomplish is that we always want to have the example docs/examples/go-md2man-2.yml work. This came up because we made changes to the spec, and then suddenly that example didn't work anymore. We don't want our documentation to be out of date with our code.

If the examples are outdated, the job should fail which will prevent merging the PR.

Keep in mind, go-md2man-1.yml intentionally does not work (see https://github.com/Azure/dalec/blob/main/docs/intro.md#building-from-sources)