feat: generate component documentation for mintlify

* feat: implement component documentation generator compatible with mintlify
* feat: improve mintlify integration
* chore: add a way to run codegen scripts standalone
* chore: remove vitepress dependency

alfred/ci.py

@@ -23,7 +23,6 @@ def ci(front, back, e2e, docs):
         alfred.invoke_command("npm.lint")
         alfred.invoke_command("npm.build")
     if docs or no_flags:
-        alfred.invoke_command("npm.docs")
         alfred.invoke_command("npm.docs.test")
     if e2e:
         alfred.invoke_command("npm.e2e", browser=e2e)

alfred/npm.py

@@ -21,10 +21,6 @@ def npm_build():
 def npm_build_custom_components():
     alfred.run("npm run ui:custom.build")
 
-@alfred.command("npm.docs", help="build docs", hidden=True)
-def npm_docs():
-    alfred.run("npm run docs:build")
-
 @alfred.command("npm.docs.test", help="test against documentation")
 def npm_docs_test():
     alfred.run("npm run docs:test")

alfred/run.py

@@ -6,7 +6,7 @@
 @alfred.command("run.docs", help="preview the documentation as a developper")
 def run_docs():
     os.chdir('docs')
-    alfred.run("npm run dev")
+    alfred.run("npm run preview")
 
 @alfred.command("run.storybook", help="preview the storybook as a developper")
 def run_storybook():

docs/codegen/core.js

@@ -0,0 +1,108 @@
+/**
+ * Generates an example of component usage in Low Code
+ *
+ * @param component {object} Name of a component
+ * @returns Example code {string}
+ *
+ * @example
+ * component.low_code_usage = core.generateLowCodeUsage(component)
+ */
+export function generateLowCodeUsage(component) {
+	let contents = "content={\n"
+	for (let fieldKey in component.fields) {
+		const properties = component.fields[fieldKey]
+		contents += `        "${fieldKey}": ${renderDefaultValue(properties)}, # ${renderPyType(properties['type'])} ${renderPyOptions(properties['options'])}\n`
+	}
+	contents += "    }"
+
+	let handlers = ""
+	if (component.events && Object.keys(component.events).length > 0) {
+		handlers += "\n,\n    handlers={\n"
+		for (let event in component.events) {
+			handlers += `        "${event}": handle_event,\n`
+		}
+		handlers += "    }"
+	}
+
+	// @ts-ignore
+	let code = `ui.${component.name.replaceAll(/\s/g, "")}(${contents.trim()}${handlers.trim()}
+)`
+	return code
+}
+
+/**
+ *
+ * @example
+ * component.event_handler = core.generateEventHandler()
+ */
+export function generateEventHandler() {
+	let code = `def handle_event(state, payload, context, ui):
+  pass
+`
+	return code
+}
+
+/**
+ *
+ * @param obj {object}
+ * @returns {*[]}
+ */
+export function values(obj) {
+	if (!obj) return [];
+
+	return Object.keys(obj).map((key) => {
+		return obj[key]
+	})
+}
+
+/**
+ *
+ * @param properties {object}
+ * @returns {string}
+ */
+function renderDefaultValue(properties) {
+	const type = properties['type'];
+	switch (type) {
+		case "Number":
+			return '0.0';
+		case "Object":
+			return "{}";
+		case "Key-Value":
+			return "{}";
+		default:
+			if (properties['options'] && properties['default']) {
+				return `"${ properties['default'] }"`;
+			}
+
+			return '""';
+	}
+}
+
+/**
+ *
+ * @param type {string}
+ * @returns {string}
+ */
+const renderPyType = (type) => {
+	switch (type) {
+		case "Number":
+			return "Union[float, str]";
+		case "Object":
+			return "Union[Dict, str]";
+		case "Key-Value":
+			return "Union[Dict, str]";
+		default:
+			return "str";
+	}
+};
+
+/**
+ *
+ * @param options {object}
+ * @returns {string}
+ */
+const renderPyOptions = (options) => {
+	if (!options) return "";
+
+	return "[" + Object.keys(options).join(", ") + "]"
+};

docs/codegen/generator_components_pages.mjs

@@ -8,33 +8,36 @@ import components from "writer-ui/components.codegen.json" with { type: "json" }
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import nunjucks from "nunjucks";
+import * as core from "./core.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const docDirectory = path.resolve(__dirname, "..", "docs");
 const docComponentsDirectory = path.resolve(docDirectory, "components");
-const componentPageTemplate = path.resolve(
-	docComponentsDirectory,
-	"component_page.md.tpl",
-);
+
 
 export async function generate() {
 	// eslint-disable-next-line no-console
 	console.log("generate doc components pages into", docComponentsDirectory);
+	nunjucks.configure({ autoescape: true });
 
 	if (!fs.existsSync(docComponentsDirectory)) {
 		fs.mkdirSync(docComponentsDirectory);
 	}
 
 	components.map((component) => {
 		// eslint-disable-next-line prettier/prettier
-		const componentPath = path.resolve(docComponentsDirectory, `${component.type}.md`);
+		const componentPageTemplate = path.resolve(docComponentsDirectory, "component_page.mdx.tpl");
 		const page = fs.readFileSync(componentPageTemplate, "utf8");
-		const renderedPage = page.replace("@{component_name}", component.name);
 
+		component.low_code_usage = core.generateLowCodeUsage(component)
+		component.event_handler = core.generateEventHandler()
+
+		const renderedPage = nunjucks.renderString(page, component);
+
+		const componentPath = path.resolve(docComponentsDirectory, `${component.type}.mdx`);
 		fs.writeFileSync(componentPath, renderedPage);
 	});
 }
-
-generate();