Hello,
with the devfile feature, we're introduced an JSON-schema for devfile yaml (used for incoming requests format validations, pojo build etc).
In addition, we also want to build some human-readable documentation from this schema, explaining the devfile format.
I did a brief research of the tools which allows to generate documentation from JSON schemas, and here (
https://github.com/eclipse/che/issues/12272#issuecomment-454783442) is the full results.
There is two libraries that looks as a most promising candidates, one of them (
https://github.com/cloudflare/json-schema-tools) creates docs in HTML format, with possibility to customise the navigation, UI templates etc, and another (
https://github.com/adobe/jsonschema2md) is generating an detailed doc in markdown format. Both of them are supported by large vendors, and support latest drafts of the JSON-schema scpecification.
To make a final decision we are looking for the criteria that might be important for committers, contributors, end-users. For example:
markdown doc can be easily put as a page on GitHub, while HTML provides better UI and easy to host or integrate with existing docs. Or just you personal preferences if any:).
Thanks, Max.
--
Max Shaposhnyk,
senior software engineer
Red Hat
![]()
