Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cesiumgs/wetzel
Generate Markdown documentation from JSON Schema
https://github.com/cesiumgs/wetzel
json-schema
Last synced: 6 days ago
JSON representation
Generate Markdown documentation from JSON Schema
- Host: GitHub
- URL: https://github.com/cesiumgs/wetzel
- Owner: CesiumGS
- License: apache-2.0
- Created: 2015-10-03T15:26:43.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2023-10-18T15:48:23.000Z (about 1 year ago)
- Last Synced: 2024-12-30T02:14:42.560Z (13 days ago)
- Topics: json-schema
- Language: JavaScript
- Size: 229 KB
- Stars: 133
- Watchers: 21
- Forks: 54
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# wetzel
Generate Markdown or AsciiDoctor documentation from JSON Schema
* [Purpose and Limitations](#purpose-and-limitations)
* [Example](#example)
* [Getting Started](#getting-started)
* [Command-Line Options](#command-line-options)
* [Common Usage](#common-usage)
* [Contributions](#contributions)
## Purpose and Limitations
This tool was developed to generate reference documentation for the [glTF](https://github.com/KhronosGroup/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`](#reference-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.
### example.byteOffset
The offset relative to the start of the buffer in bytes.
* **Type**: `integer`
* **Required**: No, default: `0`
* **Minimum**: ` >= 0`
### example.type
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](https://nodejs.org/en/) 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](https://www.npmjs.com/package/wetzel).
## 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](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#properties-reference) section and the [JSON Schema Reference Appendix](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#appendix-a-json-schema-reference) of the glTF specification, using the [glTF JSON Schema files](https://github.com/KhronosGroup/glTF/tree/main/specification/2.0/schema) as its input data.
The process is initiated from a GitHub Action in the glTF repository ([`CI.yml`](https://github.com/KhronosGroup/glTF/blob/main/.github/workflows/CI.yml)). This action runs glTF's [`Makefile`](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/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](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#properties-reference) section.
- `JsonSchemaReference.adoc` - This becomes the [JSON Schema Reference Appendix](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#appendix-a-json-schema-reference).
These files are then included into glTF's [`Specification.adoc`](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/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](https://www.khronos.org/registry/glTF/).
## Contributions
Pull requests are appreciated! Please use the same [Contributor License Agreement (CLA)](https://github.com/CesiumGS/cesium/blob/master/CONTRIBUTING.md) used for [Cesium](https://github.com/CesiumGS/cesium).
---
Developed by the Cesium team and external contributors.
