Feature request: Generate documentation from schema

[l0b0]

Is your feature request related to a problem? Please describe.

Each extension defines properties which are documented in the closest readme file. This is useful when getting a high-level understanding of the schema, for example to evaluate whether it's suitable for a particular use case. It's less useful when trying to understand the implementation of the schema itself. It would be good if it were possible to understand the schema without having to repeatedly cross-reference the readme file. At the same time it would be good if the documentation in the readme file and the schema were not duplicated, which would add to the maintenance burden and could easily be missed when implementing a change, resulting in a documentation bug. Finally, it would be good if the documentation was close to the schema, so that any mismatch between the documentation and schema were easy to spot.

Describe the solution you'd like

One way to solve this would be to move the documentation which is currently in the readme files into the relevant places in the schemas, and to generate the readme files from those schemas.

Describe alternatives you've considered

• Do nothing, leaving the schemas to not be self-documenting. This is not ideal for the reasons given above.
• Use a file format different from both JSON Schema and Markdown to generate both. I'm not aware of any simple solutions to this, and a custom one would probably be more maintenance than it's worth.
• Build our own tool to generate readme files from schemas. Ditto.
• Use a third-party tool to generate readme files from schemas. Several such tools exist:
  • JSON Schema for Humans. Examples look rather technical, and very different from the current readme format.
  • JSON Schema Markdown Tools (by Adobe, no less). Example looks rather similar to the current readme format.
  • bootprint-json-schema looks like abandonware.

Additional context