Add JSON Export for App

[mitsuhiko]

It would be great to be able to export the app with all subcommands, options and args to JSON (or something similar) so documentation tools can then pick up on it and make documentation pages.

[kbknapp]

Great suggestion, I'd love this. I have it on the back burner to add serde impls, specifically so we could get YAML and JSON. This will probably come out in the 3.x release which I keep hoping is right on the horizon...but then my day job goes and monopolizes my time. Hopefully soonish!

[mitsuhiko]

I was toying around with making a soft version of this that just spits out some json but it's not clear on what basis this could be implemented. I was taking the completion code as a reference (the zsh one spits out most of the info I need) but it uses lots of internal APIs.

I wonder if it would make sense to base the completion code on an abstraction that could become public and then also be used for other exporting.

[kbknapp]

I bet providing Debug impls would get us 90% of the way there. Not full on JSON, but close. src/args/arg_builder/valued.rs would need a manual impl because of the validator[_os], but everything else could probably be derived

[kbknapp]

Also I should also add, providing serde::Serialize for either YAML or JSON (or really any target) isn't a breaking change, and doesn't need to wait for 3.x. The only part that would be "breaking" is using serde for the Deserialize for YAML. Although, even then not technically breaking because the API used would be different than the current App::from_yaml.

[kbknapp]

So actually providing a JSON/YAML serialization doesn't seem to be that hard, and is pretty straight forward. Maybe I can knock it out this week.

I will want the serde{_json._yaml} crates to be optional and behind a feature flag. And I want to keep the minimum version of Rust 1.11 if possibe (so no #[derive(..)] or ?) for the time being.

[mitsuhiko]

You could keep serde internal for now and just provide an export to JSON / YAML function that directly writes to a writer.

[pksunkara]

Blocked by dtolnay/serde-yaml#94

[epage]

Like with #853, #1041 could help with the lifetime blocker

[MikailBag]

AFAIU, serde-yaml lifetime limitations are not really blockers: one can serialize to JSON at first, and then serialize serde_json::Value to YAML.

Also, JSON seems to be subset of YAML, so json-serialized string can be interpreted as yaml.

[epage]

Forgot which issue I was on, in general, exporting isn't blocked on the lifetime issue, only importing and only for yaml.

I'm assuming we'd want to solve these several issues (#853, #1630, this one) together, providing a single serialization/deserialization experience and not have serde for most types and then a special case for deserializing from yaml, which would make the lifetime issue a blocker.

[epage]

How much would #2914 help in this case?

The idea would be that help generation is split into the generator and formatter. This would allow user-defined formatters, like man pages. Would that work for this case?