1068 Generating context docs from schema files

package.json

@@ -26,7 +26,8 @@
     "preprepare": "npm run typegen && npm run typegen-bridging",
     "prepare": "tsdx build",
     "typegen": "node s2tQuicktypeUtil.js schemas/context src/context/ContextTypes.ts && tsdx lint src/context/ --fix",
-    "typegen-bridging": "node s2tQuicktypeUtil.js schemas/api schemas/bridging schemas/context/context.schema.json src/bridging/BridgingTypes.ts && tsdx lint src/bridging/ --fix"
+    "typegen-bridging": "node s2tQuicktypeUtil.js schemas/api schemas/bridging schemas/context/context.schema.json src/bridging/BridgingTypes.ts && tsdx lint src/bridging/ --fix",
+    "schema2markdown": "node schema2Markdown.js"
   },
   "peerDependencies": {},
   "husky": {
@@ -51,6 +52,8 @@
     "quicktype": "23.0.78",
     "tsdx": "^0.14.1",
     "tslib": "^2.0.1",
-    "typescript": "^4.0.3"
+    "typescript": "^4.0.3",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.0"
   }
 }

schema2Markdown.js

@@ -0,0 +1,254 @@
+const fse = require('fs-extra');
+const yaml = require('js-yaml');
+const path = require('path');
+
+function processProperty(propertyName, propertyDetails, schemaExamples) {
+    let markdownContent = '';
+
+    if (propertyName === 'type') {
+        markdownContent += `### Type\n\n`;
+        markdownContent += `\`${propertyDetails.const}\`\n\n`;
+    } else {
+        markdownContent += `### ${propertyDetails.title || propertyName}\n\n`;
+        markdownContent += `\`${propertyName}\`\n\n`;
+
+        if (propertyDetails.description != null) {
+            markdownContent += `${escape(propertyDetails.description)}\n\n`;
+        }
+
+        if (propertyDetails.type) {
+            markdownContent += renderType(propertyDetails.type);
+        } else {
+            const contextRef = propertyDetails.properties?.context?.$ref || propertyDetails.$ref;
+
+            if (contextRef) {
+                markdownContent += renderRef(contextRef);
+            }
+        }
+
+        if (propertyDetails.enum) {
+            markdownContent += renderEnum(propertyDetails.enum);
+        }
+
+        if (propertyDetails.allOf) {
+            markdownContent += `${propertyDetails.allOf.map((item) => renderRef(item.$ref)).join(', ')}\n\n`;
+        }
+
+        if (schemaExamples) {
+            schemaExamples.forEach((example) => {
+                markdownContent += `**Example Value**: \n`;
+                if (typeof example[propertyName] === 'object') {
+                    markdownContent += `\`\`\`json\n${JSON.stringify(example[propertyName], null, 2)}\n\`\`\`\n\n`;
+                } else if (example[propertyName]) {
+                    markdownContent += `\`${example[propertyName]}\`\n\n`;
+                }
+            });
+        }
+    }
+    return markdownContent;
+}
+
+function renderType(ref) {
+    return `**Type**: \`${ref}\`\n\n`;
+}
+
+function renderEnum(ref) {
+    // for each item in ref, wrap it in backticks and join with a comma
+    return `**Possible values**: ${ref.map((item) => `\`${item}\``).join(', ')}\n\n`;
+}
+
+function renderRef(contextRef) {
+    const [filePath, objectPath] = contextRef.split('#'); // ../api/api.schema.json, /definitions/AppIdentifier
+    const objectType = filePath.split('/').pop().split('.')[0]; // api
+
+    // FROM ../api/api.schema.json#/definitions/AppIdentifier
+    // TO   ../api/schemas/Appidentifier
+
+    // FROM timerange.schema.json#
+    // TO   timerange/schemas/timerange
+
+    let objectName = objectType;
+    if (objectPath) {
+        objectName = objectPath.split('/').pop(); // AppIdentifier
+    }
+
+    let objectRef = objectName;
+    if (filePath.startsWith('../')) {
+        objectRef = "../../" + objectType + "/schemas/" + objectName;
+    }
+
+    return `**Reference**: [${objectType}/${objectName}](${objectRef})\n\n`;
+}
+
+function hasAllOf(allOfArray) {
+    return Array.isArray(allOfArray) && 
+        allOfArray.length > 0 && 
+        allOfArray[0] != null && 
+        allOfArray[0].properties != null
+}
+
+function hasProperties(schema) {
+    return schema.properties != null;
+}
+
+// Function to generate Markdown content from JSON schema
+function generateObjectMD(schema, title, schemaFolderName, version) {
+
+    const objectName = schema.title
+
+    if (schema.title != null) {
+        title = schema.title;
+    }
+
+    let markdownContent = `# ${title}\n\n`;
+
+    if (schema.description != null) {
+        markdownContent += `${escape(schema.description)}\n\n`; 
+    }
+
+    if (schema.type) {
+        markdownContent += renderType(schema.type);
+    }
+    if (schema.enum) {
+        markdownContent += renderEnum(schema.enum);
+    }
+
+    if (hasAllOf(schema.allOf) || hasProperties(schema)) {
+        // Extract properties, required fields, and $ref from the first allOf object
+        let root = schema;
+        if (hasAllOf(schema.allOf)) {
+            root = schema.allOf[0];
+        }
+
+        const properties = root.properties;
+        const required = root.required;
+        const ref = root.$ref;
+
+        markdownContent += `## Properties\n\n`; 
+
+        for (const [propertyName, propertyDetails] of Object.entries(properties)) {
+            markdownContent += processProperty(propertyName, propertyDetails, schema.examples);
+        }
+
+        // show required properties
+        if (required && required.length > 0) {
+            markdownContent += `### Required Properties:\n\n`;
+            // for each required property show the name
+            required.forEach((propertyName) => {
+                markdownContent += `* \`${propertyName}\`\n`;
+            });
+            markdownContent += '\n';
+        } 
+
+        if (ref) {
+            markdownContent += `ref: ${ref}\n\n`;
+        }
+
+        if (schema.examples) {
+            markdownContent += `## Examples\n\n`;
+            markdownContent += '```json\n';
+            markdownContent += JSON.stringify(schema.examples, null, 2);
+            markdownContent += '\n```';
+        }
+    }
+
+    const frontMatter = generateFrontMatter(objectName, schema.description);
+
+    const outputFileName = `./website/versioned_docs/version-${version}/${schemaFolderName}/schemas/${title.replace(/\s+/g, '')}.md`;
+
+    fse.outputFileSync(outputFileName, `---\n${yaml.dump(frontMatter)}\n---\n\n${markdownContent}`);
+
+    // objectName must not contain any spaces
+    if (objectName != null) {
+        return schemaFolderName + '/schemas/' + objectName.replace(/\s+/g, '');
+    }
+}
+
+function escape(text) {
+    let output = text;
+    output = output.replace(/>/g, '\\>');
+
+    return output;
+}
+
+function generateFrontMatter(title, description) {
+    return {
+        title: `${title} Schema`,
+        description: description,
+        sidebar_label: title + ' Schema',
+    };
+}
+
+function processSchemaFile(schemaFile, schemaFolderName, version) {
+    const schemaData = fse.readJSONSync(schemaFile);
+
+    // if there is allOf, then it is an object
+    const allOfArray = schemaData.allOf;
+    let sidebarItems = [];
+    if (Array.isArray(allOfArray) && allOfArray.length > 0) {
+        sidebarItems.push(generateObjectMD(schemaData, null, schemaFolderName, version));
+    }
+    if (schemaData.definitions) {
+        for (const [objectName, objectDetails] of Object.entries(schemaData.definitions)) {
+            sidebarItems.push(generateObjectMD(objectDetails, objectName, schemaFolderName, version));
+        }
+    }
+
+    return sidebarItems;
+}
+
+function parseSchemaFolder(schemaFolderName, version) {
+    // Read all files in the schema folder
+    const schemaFiles = fse.readdirSync("./schemas/"+schemaFolderName)
+    .filter(file => file.endsWith('.json'))
+    .map(file => path.join("./schemas/"+schemaFolderName, file));
+
+    // Process each schema file
+    let sidebarItems = [];
+    for (const schemaFile of schemaFiles) {
+        sidebarItems.push(processSchemaFile(schemaFile, schemaFolderName, version));
+    }
+
+    // filter out null values
+    return sidebarItems.flat().filter(item => item);
+}
+
+function main() {
+
+    const versions = fse.readdirSync('./website/versioned_docs').map(version => version.split('-')[1]);
+
+    versions.forEach(version => {
+
+        let sidebarObject = fse.readJsonSync(`./website/versioned_sidebars/version-${version}-sidebars.json`)    
+
+        let sidebarContextObject = {
+            "type": "category",
+            "label": "Context Schemas Part",
+            "items": []
+        }
+
+        let sidebarApiObject = {
+            "type": "category",
+            "label": "API Schemas Part",
+            "items": []
+        }
+
+        sidebarApiObject.items = parseSchemaFolder('api', version);
+        sidebarContextObject.items = parseSchemaFolder('context', version);
+
+        if (sidebarObject.docs["FDC3 Standard"] == null) {
+            sidebarObject.docs["FDC3 Standard"] = [];
+        }
+
+        sidebarObject.docs["FDC3 Standard"].push(sidebarContextObject)
+        sidebarObject.docs["FDC3 Standard"].push(sidebarApiObject)
+
+        fse.outputJSONSync(
+            `./website/versioned_sidebars/version-${version}-sidebars.json`, 
+            sidebarObject, { spaces: 2 });
+    });
+}
+
+if (require.main === module) {
+    main();
+}