Generate Markdown or AsciiDoctor documentation from JSON Schema
This tool was developed to generate reference documentation for the glTF schema. As such, it doesn't support the entire JSON Schema spec, only what is needed by the glTF schema. Currently it accepts JSON Schema drafts 3, 4, 7, and 2020-12.
This JSON Schema:
{
"$schema" : "https://json-schema.org/draft/2020-12/schema",
"title" : "example",
"type" : "object",
"description" : "Example description.",
"properties" : {
"byteOffset" : {
"type" : "integer",
"description" : "The offset relative to the start of the buffer in bytes.",
"minimum" : 0,
"default" : 0
},
"type" : {
"type" : "string",
"description" : "Specifies if the elements are scalars, vectors, or matrices.",
"enum" : ["SCALAR", "VEC2", "VEC3", "VEC4", "MAT2", "MAT3", "MAT4"]
}
},
"required" : ["type"],
"additionalProperties" : false
}can be used to generate this Markdown documentation:
example(root object)
Example description.
example Properties
| Type | Description | Required | |
|---|---|---|---|
| byteOffset | integer |
The offset relative to the start of the buffer in bytes. | No, default: 0 |
| type | string |
Specifies if the elements are scalars, vectors, or matrices. | ✓ Yes |
Additional properties are not allowed.
The offset relative to the start of the buffer in bytes.
- Type:
integer - Required: No, default:
0 - Minimum:
>= 0
Specifies if the elements are scalars, vectors, or matrices.
- Type:
string - Required: ✓ Yes
- Allowed values:
"SCALAR""VEC2""VEC3""VEC4""MAT2""MAT3""MAT4"
Install Node.js if you don't already have it, clone this repo, and then:
cd wetzel
npm installRun node bin/wetzel.js and pass it the path to a file with a JSON Schema, and the generated Markdown is output to the console.
It is useful to pipe the Markdown output to the clipboard and then paste into a temporary GitHub issue for testing.
On Mac:
wetzel ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | pbcopyOn Windows:
wetzel.js ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | clipRun the tests:
npm run testThere's also a version published on npm.
- The
-loption specifies the starting header level. - The
-coption lets you specify a custom symbol to place in front of required properties. - The
-koption replaces the wordmustwith a specified keyword, such as**MUST**. - The
-poption lets you specify the relative path that should be used when referencing the schema, relative to where you store the documentation. - The
-soption lets you specify the path string that should be used when loading the schema reference paths. - The
-eoption writes an additional output file that embeds the full text of JSON schemas (AsciiDoctor mode only). - The
-moption controls the output style mode. The default isMarkdown, use-m=aforAsciiDoctormode. - The
-noption will skip writing a Table of Contents. - The
-woption will suppress any warnings about potential documentation problems that wetzel normally prints by default. - The
-doption lets you specify the root filename that will be used for writing intermediate wetzel artifacts that are useful when doing wetzel development. - The
-aoption will attempt to aggressively auto-link referenced type names in descriptions between each other. If it's too aggressive, you can add=cqoso that it only attempts to auto-link type names that are within "code-quotes only" (cqo) (e.g.:typeName) - The
-ioption lets you specify an array of schema filenames that might be referenced by others, but shouldn't get their own documentation section.
This tool is used to generate the glTF Properties Reference section and the JSON Schema Reference Appendix of the glTF specification, using the glTF JSON Schema files as its input data.
The process is initiated from a GitHub Action in the glTF repository (CI.yml). This action runs glTF's Makefile. The Makefile calls wetzel with a command similar to the following:
~/bin/wetzel.js \
-n -a=cqo -m=a \
-p "schema" \
-e "JsonSchemaReference.adoc" \
-i '["gltfchildofrootproperty.schema.json", "gltfid.schema.json", "gltfproperty.schema.json"]' \
-c "icon:check[]" \
-k "**MUST**" \
schema/glTF.schema.json > PropertiesReference.adocThis will read schema/glTF.schema.json and all referenced sub-schemas, and produce two different output files:
-
PropertiesReference.adoc- This becomes the glTF Properties Reference section. -
JsonSchemaReference.adoc- This becomes the JSON Schema Reference Appendix.
These files are then included into glTF's Specification.adoc using AsciiDoc include commands:
[[properties-reference]]
= Properties Reference
// Generated with wetzel
include::PropertiesReference.adoc[]and later:
[appendix]
[[appendix-a-json-schema-reference]]
= JSON Schema Reference (Informative)
// Generated with wetzel
include::JsonSchemaReference.adoc[]Finally, the Makefile uses asciidoctor to convert Specification.adoc and its included, generated documentation, into HTML and PDF forms of the final glTF specification document, which are then posted to the glTF Registry.
Pull requests are appreciated! Please use the same Contributor License Agreement (CLA) used for Cesium.
Developed by the Cesium team and external contributors.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent