Devfile Spec documentation generator

[skabashnyuk]

Description

Ideally, we should have a way to generate Devfile Spec documentation from Json-schema https://github.com/eclipse/che/blob/master/wsmaster/che-core-api-devfile/src/main/resources/schema/devfile.json

So far I found such generators.

• https://github.com/bootprint/bootprint-json-schema
• https://github.com/interagent/prmd
• https://github.com/cloudflarearchive/json-schema-docs-generator
• https://github.com/cloudflare/json-schema-tools

The goal of this task is to review possible options and decide which one to use or write documentation manually

[mshaposhnik]

Additional JSON schema 2 markdown tools:
https://github.com/adobe/jsonschema2md (NodeJS, Apache 2.0)
https://github.com/AnalyticalGraphicsInc/wetzel (NodeJS, Apache 2.0 )
https://github.com/rdpickard/doctor_jsonschema_md (Python, BSD-3)

the 1st one looks more preferrable for me yet

[l0rd]

@mshaposhnik +1 for the adobe jsonschema2md

[mshaposhnik]

OK i checked them all and here is the summary table:

Repository	Result Example	Building complexity
bootprint/bootprint-json-schema	https://mshaposhnik.github.io/bootprint/index.html	Low
interagent/prmd	https://github.com/mshaposhnik/spec-docs/blob/master/prmd/schema.md	Low
cloudflare/json-schema-tools	https://mshaposhnik.github.io/cloudflare_json_schema_tools/build/index.html	High
adobe/jsonschema2md	https://github.com/mshaposhnik/spec-docs/blob/master/adobe_jsonschema2md/devfile.md	High
AnalyticalGraphicsInc/wetzel	Not working (unsupported schema version)	None
rdpickard/doctor_jsonschema_md	Not working (unsupported schema version)	None

[mshaposhnik]

So the cloudflare & adobe one looks most preferrable, cloudflare lib is generating nice & pretty HTML docs with ability to add navigation menu at the left etc. while the adobe one generating nice & detailed markdown doc.

[mshaposhnik]

So I propose to start with Adobe markdown tool (as markdown more widely used for the rest of our docs), but keep an eye on the HTML generator in case we will need more pretty version. @l0rd @skabashnyuk WDYT ? Or should we discuss that wider, like on che-dev list?

[slemeur]

Nice work @mshaposhnik ! +1 to start with markdown

[l0rd]

@mshaposhnik thanks for generating all these samples. That helps :-)

I agree markdown is the best option and the format we were looking for. Anyway I have a couple of questions:

• your cloudflare/json-schema-tools sample looks like it doesn't have the definitions of all the attributes of the devfile but only the top level ones. Is it a tool limitations?
• adobe/jsonschema2md is not easy to read, for instance bootprint formatting is nicer. Is there any formatting option when you generate the markdown file?

[mshaposhnik]

Thanks for all your responces.
@l0rd yes, cloudflare allows to show all definitions, but default template requires to click on links to expand whole tree:

BTW we have some fields definitions still missing in schema itself, need to write them.

As of jsonschema2md, at first sight there is only default templates, need to investigate if there is any customization options.

[l0rd]

@mshaposhnik what's the next step here? We should publish the documentation somewhere like http://redhat-developer.github.io/devfile to be able to share the devfile format with the community.

[mshaposhnik]

So, as a result of this issue, several doc generators were tried, and the final decision made is to continue work using adobe/jsonschema2md library, based on:

• positive user experience working with it;
• resulting doc format (.md) and appearance;
• support and keeping up-to date with json-schema draft versions;
  So i propose to close this issue and proceed with implemenation in Publish Devfile documentation on http://redhat-developer.github.io/devfile #12524

[l0rd]

@mshaposhnik 👍