Better Docs

[open-cap-table-coalition]

Better Docs

[robwise]

Roger, making some good progress now.

[JSv4]

@robwise, happy to jump on a call to chat through this. In the meantime, I'll also look through the docs again and try to rework the steps I followed last time around.

[JSv4]

Per discussion on our call yesterday (1/18/22):

1. It's not just that JSONSchema2Md is verbose, it may also not be picking up required fields properly.
2. We may want to take a look at other documentation generation packages
3. Alternatively, it may make sense to roll our own given we know the structure of our own format and we don't need to design something that works for the entire JSONSchema spec.

[JSv4]

There is another (decently popular) tool to convert JSONSchema to Markdown called JSON Schema for Humans. At first glance, it seems like it's easier to change the template without forking the codebase (you can just provide a template, I think) and the default options may be more to our liking anyway. Need to experiment more.

[robwise]

@JSv4 Ben and I have been pairing and looking around at various options. A couple of potential issues with JSON Schema for Humans:

• would require both Node and Python in order to make a commit (since JSON Schema for Humans is a Python library). Currently you only need to have Node installed.
• does not seem to support inline refs (neither does jsonschema2md, but that was a reason for switching)
• markdown support is still listed as a WIP

I was hoping that maybe we could just run a quick Node script that coerces the files a bit more into the format we wanted, but would want to pair with you on exactly the changes we would need to make.

[JSv4]

All good points @robwise. Just re: the Python point, we are using Python for the validation utils, but that can be migrated to JavaScript.

Let me take a spin through the documents and see if I can't reconstruct my manual post-processing steps from last time. Can you and @bhutchings-aumni move a post-processing script forward based on those steps, once I provide them? Bit underwater here with the JSONL / container format rewrite plus all the usual firedrills, so don't think I can do both.

[JSv4]

@robwise, I wrote up the steps I followed (with a couple modifications / suggestions to account for the format changing since last time). It's in the attached .docx (didn't want to rewrite everything in MD ;-) ).

For a super quick view on the kind of transformations we need, though, we want to take something like this:

... And turn it into something more like this:

See full details here:

OCF Markdown Post-processing Steps.docx

[JSv4]

@robwise & @bhutchings-aumni, FYI, just in case you were going to do this, rewrote the validator in JavaScript so it runs in Node 14+. This will be helpful to close out Issue #48.

[robwise]

@JSv4 See comment in #57. I've been hacking on getting a fork running without all the cruft that we don't need (there is a useful schema traverser and proxy object that Adobe wrote that we could reuse to represent the schemas as an AST, but it might be a bit of work to get it working how we want).

[JSv4]

@JSv4 See comment in #57. I've been hacking on getting a fork running without all the cruft that we don't need (there is a useful schema traverser and proxy object that Adobe wrote that we could reuse to represent the schemas as an AST, but it might be a bit of work to get it working how we want).

Sounds good @robwise. Resolved the issue with JSONSchema2Md by changing our $refs to the full URIs. See PR #78

[JSv4]

@robwise, those changes are merged into the main branch, so JsonSchema2Md should be working again.