feat(scripts): add docs-json script (danielsogl#2947)

Author: camwiegert

.gitignore

@@ -4,6 +4,7 @@ node_modules/
 .tmp
 aot/
 scripts/ionic-native-bower
+scripts/docs-json/*.json
 dist/
 src/@ionic-native/plugins/**/ngx
 *.d.ts

package-lock.json

@@ -17,6 +17,7 @@
     "npmpub": "ts-node -P scripts/tsconfig.json scripts/tasks/publish",
     "lint": "gulp lint",
     "readmes": "gulp readmes",
+    "docs-json": "ts-node -P scripts/tsconfig.json scripts/docs-json",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
     "postchangelog": "git commit -am \"chore(): update changelog\"",
     "shipit": "npm run build && npm run readmes && npm run npmpub"
@@ -54,6 +55,7 @@
     "ts-node": "^8.0.2",
     "tslint": "^5.12.1",
     "tslint-ionic-rules": "0.0.21",
+    "typedoc": "^0.14.2",
     "typescript": "3.2.4",
     "uglifyjs-webpack-plugin": "^2.1.1",
     "unminified-webpack-plugin": "^2.0.0",

package.json

@@ -0,0 +1,99 @@
+import * as fs from 'fs-extra';
+import { Application } from 'typedoc';
+import { basename, dirname, resolve } from 'path';
+import { runInNewContext } from 'vm';
+
+interface Plugin {
+  packageName: string;
+  displayName: string;
+  description: string;
+  platforms: string[];
+  usage: string;
+  repo: string;
+  cordovaPlugin: {
+    name: string;
+  };
+}
+
+const rootDir = resolve(__dirname, '../..');
+const typedocTmp = resolve(__dirname, 'typedoc.tmp.json');
+const pluginsDir = resolve(rootDir, 'src/@ionic-native/plugins');
+const typedoc = new Application({
+  mode: 'modules',
+  tsconfig: resolve(rootDir, 'tsconfig.json'),
+  ignoreCompilerErrors: true
+});
+
+run(pluginsDir);
+
+async function run(pluginsDir: string) {
+  const typedocData = await generateTypedoc(pluginsDir);
+  const modules = typedocData.children.filter(isModule);
+  const plugins = modules.filter(hasPlugin).map(processPlugin);
+  await fs.outputJson(resolve(__dirname, 'plugins.json'), plugins, {
+    spaces: 2
+  });
+}
+
+async function generateTypedoc(root: string, outputPath = typedocTmp) {
+  const pluginDirs = await fs.readdir(root);
+  const paths = pluginDirs.map(dir => resolve(root, dir, 'index.ts'));
+  typedoc.generateJson(paths, outputPath);
+  return fs.readJson(outputPath);
+}
+
+function processPlugin(pluginModule): Plugin {
+  const pluginClass = pluginModule.children.find(isPlugin);
+  const decorator = getPluginDecorator(pluginClass);
+  const packageName = `@ionic-native/${basename(dirname(pluginModule.originalName))}`;
+  const displayName = getTag(pluginClass, 'name');
+  const usage = getTag(pluginClass, 'usage');
+  const description = getTag(pluginClass, 'description');
+  return {
+    packageName,
+    displayName,
+    description,
+    usage,
+    platforms: decorator.platforms,
+    repo: decorator.repo,
+    cordovaPlugin: {
+      name: decorator.plugin
+    }
+  };
+}
+
+/**
+ * Typedoc only gives us the Plugin decorator internals
+ * as a string. So, rather than try to parse that with a RegExp,
+ * we evaluate it using Node's vm module.
+ */
+const getPluginDecorator = (child: any) => {
+  if (isPlugin(child)) {
+    const decorator = child.decorators.find(d => d.name === 'Plugin');
+    return runInNewContext(`(${decorator.arguments.config})`);
+  }
+};
+
+const getTag = (child: any, tagName: string): string => {
+  if (hasTags(child)) {
+    const tag = child.comment.tags.find(t => t.tag === tagName);
+    if (tag) {
+      return tag.text;
+    }
+  }
+};
+
+const isModule = (child: any): boolean =>
+  child.kind === 1;
+
+const isClass = (child: any): boolean =>
+  child.kind === 128;
+
+const isPlugin = (child: any): boolean =>
+  isClass(child) && Array.isArray(child.decorators) && child.decorators.some(d => d.name === 'Plugin');
+
+const hasPlugin = (child: any): boolean =>
+  child.children.some(isPlugin);
+
+const hasTags = (child: any): boolean =>
+  child.comment && Array.isArray(child.comment.tags);

scripts/docs-json/index.ts

@@ -0,0 +1,3 @@
+# docs-json
+
+This script reads and generates [typedoc](https://github.com/TypeStrong/typedoc) data for each of the plugins in `src/@ionic-native/plugins`. That data is then formatted and output as `plugins.json` in this directory.