Investigate JSON Schema -> html/md generator

[ethanfrey]

It would be nice to auto-generate a static web page to show a contract's API.
If we build this in the CI and commit it, we could also easily view diffs between versions of a contract.

Let's first investigate what tools there are that can auto-generate sites from JSON Schema and compare them. Then see what other annotations we can add to our schemas to help with the generation.

[ethanfrey]

@pyramation has done a lot of relevant work in https://github.com/CosmWasm/ts-codegen

@uint if you have a clear ask / requirement, it would probably be best to talk with Dan and see if he could add another output mode to ts-codegen (it has like 5 formats, seems easy enough to add another if it is well spec'ed)

[uint]

@ethanfrey Thanks, I'll take a look. Good idea to start tackling this while we're waiting for a cosmwasm release.

[pyramation]

interesting, not to tangent too far, but I've also been thinking about generating docs/examples for usage of the ts-codegen.

I've been building a few packages and would be nice to eventually have the entire API documented with even some generated JS examples.

I can see two types of docs for two different use cases, but related in this docgen sense:

1. pure contract (JSON schema derived) methods and props that describe types, understanding contract structure.
2. ts-codegen generated examples to get users quickly building apps on contracts in JS

[ethanfrey]

Yes, this issue is about (1).

We definitely need better docs on (2) "zero to hero" for ts-codegen usage. Let's collaborate on that between Confio and Cosmology. I'd be happy to include this in our academy and official docs.

[uint]

I'm not sure if (1) belongs in ts-codegen strictly, since it seems like an aid to everyone who is not using the generated TypeScript clients/bindings, but I want to take a look if there's anything useful about what ts-codegen does to interpret the data.

[pyramation]

I haven't tested, but found these for research:

• https://github.com/adobe/jsonschema2md
• https://github.com/bootprint/bootprint-json-schema
• https://github.com/interagent/prmd

[uint]

Just not to forget: one thing that came up when we talked about it before was providing examples of valid JSON messages with realistic data (as in, not just a random integer, but an integer that would make sense for the particular contract/message).

[uint]

jsonschema2md

jsonschema2md tends to crash for me when dealing with our message types.

bootprint

bootprint seems to be missing some data. It hasn't had commits for 5 years - chances are it doesn't really support our current schema version. Also a little problematic because of this:

9 vulnerabilities (3 moderate, 6 high)

I'm not sure if it's good that Rust doc comments leak here. They'll often not be very helpful to people trying to interact with the contract. But that's probably preventable.

prmd

It seems not to support our version of JSON schema:

> prmd verify schema/execute_msg.json
Ignoring nio4r-2.5.8 because its extensions are not built. Try: gem pristine nio4r --version 2.5.8
schema/execute_msg.json: Unknown $schema: http://json-schema.org/draft-07/schema#.

draft-04 is the latest it can do.

[uint]

This probably doesn't belong to this repo.