API docs generator

.gitignore

@@ -4,6 +4,7 @@
 node_modules
 package-lock.json
 build/*
+build-api/*
 !build/wp-admin
 !build/wp-content
 !build/wp-includes

esbuild-packages.js

@@ -83,6 +83,7 @@ const configFor = (packageName, entrypoints = ['index']) => {
 		outdir: `packages/${packageName}/build`,
 	};
 };
+exports.configFor = configFor;
 
 async function main() {
 	// Build the packages first

gulpfile.js

@@ -9,8 +9,12 @@ const fs = require('fs');
 const rmAsync = util.promisify(fs.rm);
 const { spawn } = require('child_process');
 
-const { build: buildWordPressInPackage } = require('./packages/wordpress-wasm/wordpress/gulpfile')
-const { build: buildPHPInPackage } = require('./packages/php-wasm/wasm/gulpfile')
+const {
+	build: buildWordPressInPackage,
+} = require('./packages/wordpress-wasm/wordpress/gulpfile');
+const {
+	build: buildPHPInPackage,
+} = require('./packages/php-wasm/wasm/gulpfile');
 
 const packagesDir = path.join(__dirname, 'packages');
 const outputDir = path.join(__dirname, 'build');
@@ -19,60 +23,78 @@ console.log('Building the PHP WASM module...');
 console.log('Target path: $OUTDIR');
 
 async function collectBuiltWordPress() {
-    glob.sync(`${outputDir}/wp-*`).map(path => fs.rmSync(path, { force: true, recursive: true }));
-    fs.rmSync(`${outputDir}/wp.js`, { force: true });
-    fs.rmSync(`${outputDir}/wp.data`, { force: true });
+	glob.sync(`${outputDir}/wp-*`).map((path) =>
+		fs.rmSync(path, { force: true, recursive: true })
+	);
+	fs.rmSync(`${outputDir}/wp.js`, { force: true });
+	fs.rmSync(`${outputDir}/wp.data`, { force: true });
 
-    const wpDir = `${packagesDir}/wordpress-wasm/build-wp`;
-    await asyncPipe(
-        gulp.src([`${wpDir}/**/*`], { "base": wpDir }).pipe(gulp.dest(outputDir))
-    );
+	const wpDir = `${packagesDir}/wordpress-wasm/build-wp`;
+	await asyncPipe(
+		gulp.src([`${wpDir}/**/*`], { base: wpDir }).pipe(gulp.dest(outputDir))
+	);
 }
 
 async function collectBuiltPHP() {
-    glob.sync(`${outputDir}/php.js`).map(path => fs.rmSync(path, { force: true }));
-    fs.rmSync(`${outputDir}/php.wasm`, { force: true });
+	glob.sync(`${outputDir}/php.js`).map((path) =>
+		fs.rmSync(path, { force: true })
+	);
+	fs.rmSync(`${outputDir}/php.wasm`, { force: true });
 
-    await asyncPipe(
-        gulp.src([
-            `${packagesDir}/php-wasm/build-wasm/*`,
-        ]).pipe(gulp.dest(outputDir))
-    );
+	await asyncPipe(
+		gulp
+			.src([`${packagesDir}/php-wasm/build-wasm/*`])
+			.pipe(gulp.dest(outputDir))
+	);
 }
 
 async function buildHtaccess() {
-    const htAccess = glob.sync(`${packagesDir}/*/build/.htaccess`)
-        .map((filePath) => fs.readFileSync(filePath).toString())
-        .join("\n");
-    const outPath = `${outputDir}/.htaccess`;
-    fs.writeFileSync(outPath, htAccess);
-    console.log('  ' + outPath);
+	const htAccess = glob
+		.sync(`${packagesDir}/*/build/.htaccess`)
+		.map((filePath) => fs.readFileSync(filePath).toString())
+		.join('\n');
+	const outPath = `${outputDir}/.htaccess`;
+	fs.writeFileSync(outPath, htAccess);
+	console.log('  ' + outPath);
 }
 
 async function buildModules() {
-    const { main: esbuildModules } = require('./esbuild-packages');
-    await esbuildModules();
+	const { main: esbuildModules } = require('./esbuild-packages');
+	await esbuildModules();
+}
+
+async function buildDocGenerator() {
+	const { configFor } = require('./esbuild-packages');
+	const esConfig = configFor('typescript-reference-doc-generator');
+	const { build } = require('esbuild');
+	build({
+		...esConfig,
+		platform: 'node',
+	});
 }
 
 exports.copyBuiltWordPress = collectBuiltWordPress;
 exports.collectBuiltPHP = collectBuiltPHP;
 exports.copyBuiltAssets = gulp.parallel(collectBuiltWordPress, collectBuiltPHP);
 exports.buildHtaccess = buildHtaccess;
-exports.buildWordPress = gulp.series(buildWordPressInPackage, collectBuiltWordPress);
+exports.buildWordPress = gulp.series(
+	buildWordPressInPackage,
+	collectBuiltWordPress
+);
 exports.buildPHP = gulp.series(buildPHPInPackage, collectBuiltPHP);
 exports.buildJS = buildModules;
+exports.buildDocGenerator = buildDocGenerator;
 
 exports.buildAll = gulp.parallel(
-    exports.buildHtaccess,
-    exports.buildWordPress,
-    exports.buildPHP,
-    exports.buildJS
+	exports.buildHtaccess,
+	exports.buildWordPress,
+	exports.buildPHP,
+	exports.buildJS,
+	exports.buildDocGenerator
 );
 
-
 function asyncPipe(pipe) {
-    return new Promise(async (resolve, reject) => {
-        pipe.on('finish', resolve)
-            .on('error', reject);
-    });
+	return new Promise(async (resolve, reject) => {
+		pipe.on('finish', resolve).on('error', reject);
+	});
 }

package.json

@@ -6,6 +6,7 @@
   "private": "true",
   "scripts": {
     "dev": "node esbuild-packages.js --watch",
+    "dev:docs:html": "vitepress dev docs/api",
     "build": "gulp build:js",
     "build:all": "npm run clean; gulp buildAll",
     "build:js": "gulp buildJS",
@@ -14,6 +15,8 @@
     "build:php": "npm run build:php:web",
     "build:php:web": "PLATFORM=web gulp buildPHP",
     "build:php:node": "PLATFORM=node gulp buildPHP",
+    "build:api-docs": "bash scripts/refresh-api-docs.sh",
+    "build:doc-generator": "gulp buildDocGenerator",
     "clean": "rm -rf build/* packages/*/build-*/*",
     "format": "prettier --write packages/src",
     "lint:js": "eslint \"./packages/src/**/*.{js,mjs,ts}\"",
@@ -33,13 +36,17 @@
   "author": "The WordPress contributors",
   "license": "Apache-2.0",
   "dependencies": {
+    "@microsoft/tsdoc": "^0.14.2",
     "glob": "^8.0.3",
     "php-wasm": "file:packages/php-wasm",
     "php-wasm-browser": "file:packages/php-wasm-browser",
     "wordpress-wasm": "file:packages/wordpress-wasm",
     "yargs": "^17.5.1"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7. 33.5",
+    "@microsoft/api-extractor-model ": "7.25.2",
+    "@microsoft/tsdoc": "0.14.2",
     "@wordpress/docgen": "^1.29.0",
     "@wordpress/eslint-plugin": "^13.0.0",
     "chokidar-cli": "^3.0.0",
@@ -56,6 +63,11 @@
     "live-server": "^1.2.2",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.7.1",
-    "request": "^2.88.2"
+    "request": "^2.88.2",
+    "vitepress": "^1.0.0-alpha.26",
+    "vue": "^3.2.41",
+    "colors": "~1.2.1",
+    "typescript": "4.8.4",
+    "@types/node": "12.20.24"
   }
 }

packages/php-wasm-browser/api-extractor.browser.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-base.json",
+  "mainEntryPointFilePath": "<projectFolder>/build-types/index.d.ts",
+  "docModel": {
+    "apiJsonFilePath": "<projectFolder>/build-api/<unscopedPackageName>-browser.api.json"
+  }
+}

packages/php-wasm-browser/api-extractor.service-worker.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-base.json",
+  "mainEntryPointFilePath": "<projectFolder>/build-types/service-worker/worker-library.d.ts",
+  "docModel": {
+    "apiJsonFilePath": "<projectFolder>/build-api/<unscopedPackageName>-service-worker.api.json"
+  }
+}

packages/php-wasm-browser/api-extractor.worker-thread.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-base.json",
+  "mainEntryPointFilePath": "<projectFolder>/build-types/worker-thread/worker-library.d.ts",
+  "docModel": {
+    "apiJsonFilePath": "<projectFolder>/build-api/<unscopedPackageName>-worker-thread.api.json"
+  }
+}

packages/php-wasm/api-extractor.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-base.json",
+  "mainEntryPointFilePath": "<projectFolder>/build-types/index.d.ts"
+}

packages/typescript-reference-doc-generator/LICENSE

@@ -0,0 +1,28 @@
+This package, typescript-reference-doc-generator, is based on @microsoft/api-documenter.
+
+Here's the original LICENSE for typescript-reference-doc-generator:
+
+@microsoft/api-documenter
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/typescript-reference-doc-generator/bin/api-extractor.js

@@ -0,0 +1,2 @@
+require('./patch-tsdoc');
+require('../../../node_modules/.bin/api-extractor');

packages/typescript-reference-doc-generator/bin/generate-docs.js

@@ -0,0 +1,60 @@
+require('./patch-tsdoc');
+
+const fs = require('fs');
+const yargs = require('yargs');
+let generator;
+try {
+	generator = require(__dirname + '/../build/index');
+} catch (e) {
+	console.error(e);
+	throw new Error(
+		'Build the typescript-reference-doc-generator package to generate the documentation. ' +
+			'Run `npm run build:doc-generator` in the repo root.'
+	);
+}
+
+const { ApiModelBuilder, MarkdownDocumenter } = generator;
+
+const { i: inputFolder, o: outputFolder } = yargs(process.argv.slice(2))
+	.command('build', 'Builds the project files')
+	.options({
+		'input-folder': {
+			alias: 'i',
+			type: 'string',
+			required: true,
+			describe:
+				'The input folder containing the *.api.json files to be processed.',
+		},
+		'output-folder': {
+			alias: 'o',
+			type: 'string',
+			required: true,
+			describe:
+				'The output folder where the documentation will be written. ANY EXISTING CONTENTS WILL BE DELETED!',
+		},
+	})
+	.help()
+	.alias('help', 'h').argv;
+
+if (!fs.existsSync(inputFolder)) {
+	throw new Error('The input folder does not exist: ' + inputFolder);
+}
+
+try {
+	fs.mkdirSync(outputFolder, { recursive: true });
+} catch (e) {
+	if (!fs.existsSync(outputFolder)) {
+		throw e;
+	}
+}
+
+const builder = new ApiModelBuilder();
+const apiModel = builder.buildApiModel(inputFolder);
+
+const markdownDocumenter = new MarkdownDocumenter({
+	apiModel,
+	documenterConfig: undefined,
+	outputFolder,
+});
+
+markdownDocumenter.generateFiles();

packages/typescript-reference-doc-generator/bin/merge-api-models.js

@@ -0,0 +1,68 @@
+const fs = require('fs');
+
+// Iterate over the JSON files in the directory passed via the first argument
+const extractedApis = process.argv
+	.slice(2)
+	.map((file) => JSON.parse(fs.readFileSync(file, 'utf8')));
+
+const seen = new Set();
+
+const firstEntryCloned = JSON.parse(JSON.stringify(extractedApis[0]));
+const result = {
+	...firstEntryCloned,
+	members: [],
+};
+
+for (const api of extractedApis) {
+	if (!seen.has(api.members[0].canonicalReference)) {
+		api.members[0].name = api.members[0].canonicalReference.split('!')[0];
+		result.members.push({
+			...api.members[0],
+			members: [],
+		});
+		seen.add(api.members[0].canonicalReference);
+	}
+
+	for (const apiMember of api.members[0].members) {
+		if (!seen.has(apiMember.canonicalReference)) {
+			// api-documenter only supports a single entrypoint per file
+			result.members[0].members.push(
+				fixCrossPackageReferences(apiMember, result.members[0].name)
+			);
+			seen.add(apiMember.canonicalReference);
+		}
+	}
+}
+
+function fixCrossPackageReferences(obj, currentPackage) {
+	if (!obj) {
+		return obj;
+	} else if (Array.isArray(obj)) {
+		return obj.map((subMember) =>
+			fixCrossPackageReferences(subMember, currentPackage)
+		);
+	} else if (
+		obj.kind === 'Reference' &&
+		obj.canonicalReference.includes('!')
+	) {
+		const [packageName] = obj.canonicalReference.split('!');
+		// if (packageName !== currentPackage)
+		{
+			return {
+				...obj,
+				canonicalReference: `${packageName}/${obj.canonicalReference}`,
+			};
+		}
+	} else if (typeof obj === 'object') {
+		const updatedObj = {};
+		for (const [key, value] of Object.entries(obj)) {
+			updatedObj[key] = fixCrossPackageReferences(value, currentPackage);
+		}
+		return updatedObj;
+	}
+
+	return obj;
+}
+
+// Write the result to stdout
+console.log(JSON.stringify(result, null, 2));