diff --git a/lib/generateMarkdown.js b/lib/generateMarkdown.js index 738d052..953b1e4 100644 --- a/lib/generateMarkdown.js +++ b/lib/generateMarkdown.js @@ -220,6 +220,7 @@ function getSchemaMarkdown(schema, fileName, headerLevel, suppressWarnings, sche // Render section for each property var title = defaultValue(schema.title, suppressWarnings ? '' : 'WETZEL_WARNING: title not defined'); md += createPropertiesDetails(schema, title, headerLevel + 1, knownTypes, autoLink); + md += createExamples(schema, headerLevel); } return md; @@ -254,6 +255,16 @@ function createPropertiesSummary(schema, knownTypes, autoLink) { return md; } +function createExamples(schema, headerLevel) { + var examples = schema.examples; + if (!defined(examples)) return ''; + var md = style.getHeaderMarkdown(headerLevel) + ' Examples' + '\n\n'; + for (const example of examples) { + md += style.bulletItem(style.defaultValue(example, schema.type), 0); + } + return md; +} + function createPropertiesDetails(schema, title, headerLevel, knownTypes, autoLink) { var headerMd = style.getHeaderMarkdown(headerLevel); var md = ''; diff --git a/lib/style.js b/lib/style.js index e5a8ba1..7ec85fb 100644 --- a/lib/style.js +++ b/lib/style.js @@ -339,6 +339,15 @@ function styleBold(string) { */ function styleCode(code) { if (defined(code)) { + // If it's an object, just serialize it. + if (typeof code === 'object') { + // Someday may want to use a code fence if it's longer than, say, 88 + // chars, but that would require keeping track of the current + // indentation. Not really how things are designed to work right + // now. So add spaces but let it display as a single line for now. + return '`' + JSON.stringify(code, null, 1).replace(/\n/g, '').replace(/([{[]) /, '$1') + '`'; + } + // The object might be a string or it might be a number or something else. // Let's make sure it's a string first. var stringified = code.toString(); diff --git a/test/test-golden/v2020-12-embed.adoc b/test/test-golden/v2020-12-embed.adoc index 0335628..71a0972 100644 --- a/test/test-golden/v2020-12-embed.adoc +++ b/test/test-golden/v2020-12-embed.adoc @@ -48,6 +48,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: +** `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` === Image.mimeType @@ -66,6 +68,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: `>= 0` +* **Examples**: +** `3` +** `0` === Image.fraction @@ -83,5 +88,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` ** Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: +** `[1.3, 4.03, 42]` +** `[18, 0.1, 1.1]` +== Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-keyword.md b/test/test-golden/v2020-12-keyword.md index d273d1e..142a067 100644 --- a/test/test-golden/v2020-12-keyword.md +++ b/test/test-golden/v2020-12-keyword.md @@ -27,6 +27,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: + * `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` ### Image.mimeType @@ -45,6 +47,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: ` >= 0` +* **Examples**: + * `3` + * `0` ### Image.fraction @@ -62,5 +67,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` * Each element in the array **MUST** be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: + * `[1.3, 4.03, 42]` + * `[18, 0.1, 1.1]` +## Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-linked.adoc b/test/test-golden/v2020-12-linked.adoc index 31e379e..d917cab 100644 --- a/test/test-golden/v2020-12-linked.adoc +++ b/test/test-golden/v2020-12-linked.adoc @@ -50,6 +50,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: +** `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` ==== Image.mimeType @@ -68,6 +70,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: `>= 0` +* **Examples**: +** `3` +** `0` ==== Image.fraction @@ -85,5 +90,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` ** Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: +** `[1.3, 4.03, 42]` +** `[18, 0.1, 1.1]` +=== Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-linked.md b/test/test-golden/v2020-12-linked.md index 72334bc..c706bac 100644 --- a/test/test-golden/v2020-12-linked.md +++ b/test/test-golden/v2020-12-linked.md @@ -29,6 +29,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: + * `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` #### Image.mimeType @@ -47,6 +49,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: ` >= 0` +* **Examples**: + * `3` + * `0` #### Image.fraction @@ -64,5 +69,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` * Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: + * `[1.3, 4.03, 42]` + * `[18, 0.1, 1.1]` +### Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-remote.adoc b/test/test-golden/v2020-12-remote.adoc index 72613b3..45d5fcc 100644 --- a/test/test-golden/v2020-12-remote.adoc +++ b/test/test-golden/v2020-12-remote.adoc @@ -48,6 +48,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: +** `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` === Image.mimeType @@ -66,6 +68,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: `>= 0` +* **Examples**: +** `3` +** `0` === Image.fraction @@ -83,5 +88,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` ** Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: +** `[1.3, 4.03, 42]` +** `[18, 0.1, 1.1]` +== Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-remote.md b/test/test-golden/v2020-12-remote.md index bf67935..8f62242 100644 --- a/test/test-golden/v2020-12-remote.md +++ b/test/test-golden/v2020-12-remote.md @@ -27,6 +27,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: + * `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` ### Image.mimeType @@ -45,6 +47,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: ` >= 0` +* **Examples**: + * `3` + * `0` ### Image.fraction @@ -62,5 +67,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` * Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: + * `[1.3, 4.03, 42]` + * `[18, 0.1, 1.1]` +## Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-simple.adoc b/test/test-golden/v2020-12-simple.adoc index 2c58946..bf69acd 100644 --- a/test/test-golden/v2020-12-simple.adoc +++ b/test/test-golden/v2020-12-simple.adoc @@ -48,6 +48,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: +** `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` === Image.mimeType @@ -66,6 +68,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: `>= 0` +* **Examples**: +** `3` +** `0` === Image.fraction @@ -83,5 +88,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` ** Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: +** `[1.3, 4.03, 42]` +** `[18, 0.1, 1.1]` +== Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-golden/v2020-12-simple.md b/test/test-golden/v2020-12-simple.md index fb23e0a..e68c022 100644 --- a/test/test-golden/v2020-12-simple.md +++ b/test/test-golden/v2020-12-simple.md @@ -27,6 +27,8 @@ The URI (or IRI) of the image. Relative paths are relative to the current glTF * **Type**: `string` * **Required**: No * **Format**: iri-reference +* **Examples**: + * `"https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png"` ### Image.mimeType @@ -45,6 +47,9 @@ The index of the bufferView that contains the image. This field **MUST NOT** be * **Type**: `integer` * **Required**: No * **Minimum**: ` >= 0` +* **Examples**: + * `3` + * `0` ### Image.fraction @@ -62,5 +67,12 @@ An array of three fractional numbers. * **Type**: `number` `[3]` * Each element in the array must be greater than `0` and less than `1`. * **Required**: No, default: `[0.1,0.2,0.3]` +* **Examples**: + * `[1.3, 4.03, 42]` + * `[18, 0.1, 1.1]` +## Examples + +* `{"uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", "mimeType": "image/png"}` +* `{"bufferView": 2, "fraction": 0.3, "moreFractions": [ 1.1, 2.2, 3.3 ]}` diff --git a/test/test-schemas/v2020-12/image.schema.json b/test/test-schemas/v2020-12/image.schema.json index 9bc913d..3d88820 100644 --- a/test/test-schemas/v2020-12/image.schema.json +++ b/test/test-schemas/v2020-12/image.schema.json @@ -10,7 +10,10 @@ "description": "The URI (or IRI) of the image.", "format": "iri-reference", "gltf_detailedDescription": "The URI (or IRI) of the image. Relative paths are relative to the current glTF asset. Instead of referencing an external file, this field **MAY** contain a `data:`-URI. This field **MUST NOT** be defined when `bufferView` is defined.", - "gltf_uriType": "image" + "gltf_uriType": "image", + "examples": [ + "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png" + ] }, "mimeType": { "anyOf": [ @@ -29,7 +32,8 @@ "bufferView": { "type": "integer", "minimum": 0, - "description": "The index of the bufferView that contains the image. This field **MUST NOT** be defined when `uri` is defined." + "description": "The index of the bufferView that contains the image. This field **MUST NOT** be defined when `uri` is defined.", + "examples": [3, 0] }, "fraction": { "type": "number", @@ -47,7 +51,11 @@ }, "minItems" : 3, "maxItems" : 3, - "default" : [0.1, 0.2, 0.3] + "default" : [0.1, 0.2, 0.3], + "examples": [ + [1.3, 4.03, 42.0], + [18.0, 0.1, 1.1] + ] } }, "dependencies": { @@ -56,5 +64,16 @@ "oneOf": [ { "required": [ "uri" ] }, { "required": [ "bufferView" ] } + ], + "examples": [ + { + "uri": "https://raw.githubusercontent.com/KhronosGroup/glTF/main/specification/figures/gltf.png", + "mimeType": "image/png" + }, + { + "bufferView": 2, + "fraction": 0.3, + "moreFractions": [1.1, 2.2, 3.3] + } ] }