{"id":19500201,"url":"https://github.com/cesiumgs/wetzel","last_synced_at":"2025-05-16T06:06:23.548Z","repository":{"id":39582022,"uuid":"43603533","full_name":"CesiumGS/wetzel","owner":"CesiumGS","description":"Generate Markdown documentation from JSON Schema","archived":false,"fork":false,"pushed_at":"2025-01-05T15:22:51.000Z","size":234,"stargazers_count":135,"open_issues_count":17,"forks_count":54,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-05-09T01:17:25.689Z","etag":null,"topics":["json-schema"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CesiumGS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-03T15:26:43.000Z","updated_at":"2025-04-04T03:03:20.000Z","dependencies_parsed_at":"2022-07-04T11:12:04.966Z","dependency_job_id":"4c34db2b-39b7-4ecd-8dda-55cb4da26ceb","html_url":"https://github.com/CesiumGS/wetzel","commit_stats":{"total_commits":135,"total_committers":14,"mean_commits":9.642857142857142,"dds":"0.49629629629629635","last_synced_commit":"f30c4fb4655facfcf91fca745f6188d5646c3f21"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2Fwetzel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2Fwetzel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2Fwetzel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CesiumGS%2Fwetzel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CesiumGS","download_url":"https://codeload.github.com/CesiumGS/wetzel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema"],"created_at":"2024-11-10T22:07:52.843Z","updated_at":"2025-05-16T06:06:18.539Z","avatar_url":"https://github.com/CesiumGS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wetzel\n\nGenerate Markdown or AsciiDoctor documentation from JSON Schema\n\n* [Purpose and Limitations](#purpose-and-limitations)\n* [Example](#example)\n* [Getting Started](#getting-started)\n* [Command-Line Options](#command-line-options)\n* [Common Usage](#common-usage)\n* [Contributions](#contributions)\n\n## Purpose and Limitations\n\nThis 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.\n\n## Example\n\nThis JSON Schema:\n```json\n{\n    \"$schema\" : \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\" : \"example\",\n    \"type\" : \"object\",\n    \"description\" : \"Example description.\",\n    \"properties\" : {\n        \"byteOffset\" : {\n            \"type\" : \"integer\",\n            \"description\" : \"The offset relative to the start of the buffer in bytes.\",\n            \"minimum\" : 0,\n            \"default\" : 0\n        },\n        \"type\" : {\n            \"type\" : \"string\",\n            \"description\" : \"Specifies if the elements are scalars, vectors, or matrices.\",\n            \"enum\" : [\"SCALAR\", \"VEC2\", \"VEC3\", \"VEC4\", \"MAT2\", \"MAT3\", \"MAT4\"]\n        }\n    },\n    \"required\" : [\"type\"],\n    \"additionalProperties\" : false\n}\n```\n\ncan be used to generate this Markdown documentation:\n\n* [`example`](#reference-example) (root object)\n\n\n---------------------------------------\n\u003ca name=\"reference-example\"\u003e\u003c/a\u003e\n## example\n\nExample description.\n\n**`example` Properties**\n\n|   |Type|Description|Required|\n|---|---|---|---|\n|**byteOffset**|`integer`|The offset relative to the start of the buffer in bytes.|No, default: `0`|\n|**type**|`string`|Specifies if the elements are scalars, vectors, or matrices.| \u0026#10003; Yes|\n\nAdditional properties are not allowed.\n\n### example.byteOffset\n\nThe offset relative to the start of the buffer in bytes.\n\n* **Type**: `integer`\n* **Required**: No, default: `0`\n* **Minimum**: ` \u003e= 0`\n\n### example.type\n\nSpecifies if the elements are scalars, vectors, or matrices.\n\n* **Type**: `string`\n* **Required**:  \u0026#10003; Yes\n* **Allowed values**:\n    * `\"SCALAR\"`\n    * `\"VEC2\"`\n    * `\"VEC3\"`\n    * `\"VEC4\"`\n    * `\"MAT2\"`\n    * `\"MAT3\"`\n    * `\"MAT4\"`\n\n---\n\n## Getting Started\n\nInstall [Node.js](https://nodejs.org/en/) if you don't already have it, clone this repo, and then:\n```sh\ncd wetzel\nnpm install\n```\nRun `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.\n\nIt is useful to pipe the Markdown output to the clipboard and then paste into a temporary GitHub issue for testing.\n\nOn Mac:\n```sh\nwetzel ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | pbcopy\n```\n\nOn Windows:\n```sh\nwetzel.js ../glTF/specification/2.0/schema/accessor.schema.json -l 2 | clip\n```\n\nRun the tests:\n```sh\nnpm run test\n```\n\nThere's also a version [published on npm](https://www.npmjs.com/package/wetzel).\n\n## Command-Line Options\n\n* The `-l` option specifies the starting header level.\n* The `-c` option lets you specify a custom symbol to place in front of required properties.\n* The `-k` option replaces the word `must` with a specified keyword, such as `**MUST**`.\n* The `-p` option lets you specify the relative path that should be used when referencing the schema, relative to where you store the documentation.\n* The `-s` option lets you specify the path string that should be used when loading the schema reference paths.\n* The `-e` option writes an additional output file that embeds the full text of JSON schemas (AsciiDoctor mode only).\n* The `-m` option controls the output style mode. The default is `Markdown`, use `-m=a` for `AsciiDoctor` mode.\n* The `-n` option will skip writing a Table of Contents.\n* The `-w` option will suppress any warnings about potential documentation problems that wetzel normally prints by default.\n* 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.\n* 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``)\n* 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.\n\n## Common Usage\n\nThis 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.\n\nThe 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:\n\n```sh\n~/bin/wetzel.js \\\n    -n -a=cqo -m=a \\\n    -p \"schema\" \\\n    -e \"JsonSchemaReference.adoc\" \\\n    -i '[\"gltfchildofrootproperty.schema.json\", \"gltfid.schema.json\", \"gltfproperty.schema.json\"]' \\\n    -c \"icon:check[]\" \\\n    -k \"**MUST**\" \\\n    schema/glTF.schema.json \u003e PropertiesReference.adoc\n```\n\nThis will read `schema/glTF.schema.json` and all referenced sub-schemas, and produce two different output files:\n\n- `PropertiesReference.adoc` - This becomes the [glTF Properties Reference](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#properties-reference) section.\n\n- `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).\n\nThese 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:\n\n```adoc\n[[properties-reference]]\n= Properties Reference\n\n// Generated with wetzel\ninclude::PropertiesReference.adoc[]\n```\n\nand later:\n\n```adoc\n[appendix]\n[[appendix-a-json-schema-reference]]\n= JSON Schema Reference (Informative)\n\n// Generated with wetzel\ninclude::JsonSchemaReference.adoc[]\n```\n\nFinally, 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/).\n\n## Contributions\n\nPull 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).\n\n---\n\nDeveloped by the Cesium team and external contributors.\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://cesium.com/\"\u003e\u003cimg src=\"doc/cesium.png\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesiumgs%2Fwetzel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcesiumgs%2Fwetzel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcesiumgs%2Fwetzel/lists"}