Merge pull request #63 from theory/improve-examples

Improve examples

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 = '';

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();

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 ]}`

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 ]}`

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 ]}`

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 ]}`

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 ]}`

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 ]}`

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 ]}`

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 ]}`

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]
+        }
     ]
 }