wetzel

Generate Markdown or AsciiDoctor documentation from JSON Schema

* Purpose and Limitations
* Example
* Getting Started
* Command-Line Options
* Common Usage
* Contributions

Purpose and Limitations

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.

Example

This JSON Schema:
``json
{
"$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

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.

$3

The offset relative to the start of the buffer in bytes.

* Type: integer
* Required: No, default: 0
* Minimum: >= 0

$3

Specifies if the elements are scalars, vectors, or matrices.

* Type: string
* Required: ✓ Yes
* Allowed values:
* "SCALAR"
* "VEC2"
* "VEC3"
* "VEC4"
* "MAT2"
* "MAT3"
* "MAT4"

---

Getting Started

Install Node.js if you don't already have it, clone this repo, and then:
`sh
cd wetzel
npm install
`
Run 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:
`sh
wetzel ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | pbcopy
`

On Windows:
`sh
wetzel.js ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | clip
`

Run the tests:
`sh
npm run test
`

There's also a version published on npm.

Command-Line Options

* The -l option specifies the starting header level.
* The -c option lets you specify a custom symbol to place in front of required properties.
* The -k option replaces the word must with a specified keyword, such as MUST.
* The -p option lets you specify the relative path that should be used when referencing the schema, relative to where you store the documentation.
* The -s option lets you specify the path string that should be used when loading the schema reference paths.
* The -e option writes an additional output file that embeds the full text of JSON schemas (AsciiDoctor mode only).
* The -m option controls the output style mode. The default is Markdown, use -m=a for AsciiDoctor mode.
* The -n option will skip writing a Table of Contents.
* The -w option will suppress any warnings about potential documentation problems that wetzel normally prints by default.
* The -d option lets you specify the root filename that will be used for writing intermediate wetzel artifacts that are useful when doing wetzel development.
* The -a option will attempt to aggressively auto-link referenced type names in descriptions between each other. If it's too aggressive, you can add =cqo so that it only attempts to auto-link type names that are within "code-quotes only" (cqo) (e.g.: typeName)
* The -i option lets you specify an array of schema filenames that might be referenced by others, but shouldn't get their own documentation section.

Common Usage

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:

`sh
~/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.adoc
`

This 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:

`adoc
[[properties-reference]]
= Properties Reference

// Generated with wetzel
include::PropertiesReference.adoc[]
`

and later:

`adoc
[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.

Contributions

Pull requests are appreciated! Please use the same Contributor License Agreement (CLA) used for Cesium.

---

Developed by the Cesium team and external contributors.