Removes random doc command from CLI

[codefromthecrypt]

This removes "getenvoy doc" which generates markdown. This is random and generating documentation shouldn't be a runtime concern. We should focus on "help" and things users ask for like auto-complete

[codefromthecrypt]

most tech debt I've noticed, after removal, simplifies or removes a little bit of dodgy things in our go.sum. Let's keep doing this.

[mathetake]

noticed that this is used in https://github.com/tetratelabs/getenvoy.io/blob/master/ci/regen#L7 but is definitely should not be compiled into the released binary.

[codefromthecrypt]

Thanks. I think we should remove this from the website. There's no "reference" aspect about it, it is just dumping the CLI help output.

…

[mathetake]

I think these docs are still useful for people just skimming though the getenvoy website to see what kind of commands we have and what they can do with 'getenvoy'. So I'm in favor of retaining these docs, though we should definitely remove this from the binary. So how about having doc gen command without compiling it into the release binary so that we could leverage it to update the website (e.g. pushing Markdowns changes to getenvoy.io on our release job in this repository)?

[codefromthecrypt]

@mathetake with repos spread as they are (tetratelabs-attic/getenvoy.io#162), it seems really coupled to me, and I'm glad we agree on this.

The reason I advocated for removal is that I don't think the docs as they are are handled well with codegen. There are other ways to document which result in tested examples. Ours are not tested and they easily drift, though this is also a problem in the CLI help output as well.

In other words, I think we can do better docs than what we are doing here, and it doesn't necessarily mean we need to use a CLI library to generate them. That said, an alternative is maybe better as a "show not tell" thing.

Options meanwhile include writing docs like normal people, ad-hoc generation, or even parsing the CLI output instead of baking it into the binary.

[codefromthecrypt]

plus we should also be aware that there are only 3 commands now :) they are all silly easy and sometimes the cure is worse than the disease. In other words "writing docs like normal people" is even easier when the tool isn't complicated

[codefromthecrypt]

looking at the underlying thing, if we assume the framework is possible to do good docs with, composition as a build-time concern seems the best way out to me.

For example, URLfave, you can generate man pages or markdown. The way to do it is to import an existing CLI then call ToMarkdown() with a destination dir in mind.

https://github.com/urfave/cli/blob/master/docs_test.go

I think this is similar to what you mean @mathetake basically we don't need to make this a part of the binary, we need to run it with the same tag as the release.. either as a single step (eg markdown and CLI are in the same repo), or if not push (the release here pushes to the UI repo) or pull (the UI repo has the code to add Markdown and run it)

Question is.. is this similar or am I off?

[mathetake]

I think this is similar to what you mean @mathetake basically we don't need to make this a part of the binary, we need to run it with the same tag as the release.. either as a single step (eg markdown and CLI are in the same repo), or if not push (the release here pushes to the UI repo) or pull (the UI repo has the code to add Markdown and run it)

yeah this is what i meant.

[codefromthecrypt]

closed by #264