feat: Improve generate_docs

- Migrate to use docgen.json
- Copy included libs (core) sources into src, i.e., src/@uirouter/core
- Use updated typedoc-plugin-ui-router

Author: christopherthielen

findSemverPackage.js

@@ -9,7 +9,7 @@ module.exports = function findSemverPackage(packageName, semver) {
   } else if (lines.length === 1) {
     return lines[ 0 ];
   } else {
-    const line = stdout.split(/\n/).pop().trim();
+    const line = stdout.trim().split(/\n/).pop().trim();
     const [, version] = /.* '(.*)'$/.exec(line) || [];
     if (!version) {
       console.log({ stdout, line });

generate_docs.js

@@ -1,30 +1,45 @@
 #!/usr/bin/env node
 
-const publishYalcPackage = require('./publish_yalc_package');
 const findSemverPackage = require('./findSemverPackage');
 const shelljs = require('shelljs');
 const nodeCleanup = require('node-cleanup');
 const fs = require('fs');
 const path = require('path');
-const has = require('lodash').has;
+const _ = require('lodash');
 const util = require('./util');
 const _exec = util._exec;
+const options = require('yargs').option('noclean', { boolean: true, default: false }).argv;
 
-util.packageDir();
-const TYPEDOC_CONFIG = getTypedocConfig();
-const TS_CONFIG = JSON.parse(fs.readFileSync('./tsconfig.json'));
 const PACKAGE_DIR = process.cwd();
-const PACKAGE_JSON = JSON.parse(fs.readFileSync('package.json'));
+const SRC_DIR = `${PACKAGE_DIR}/src`;
+const DOCGENCONFIG_PATH = `${PACKAGE_DIR}/docgen.json`;
+const TSCONFIG_PATH = `${PACKAGE_DIR}/tsconfig.json`;
+const PACKAGEJSON_PATH = `${PACKAGE_DIR}/package.json`;
+
+util.packageDir();
+
+if (!fs.existsSync(SRC_DIR)) { throw new Error(`${SRC_DIR} does not exist`) }
+if (!fs.existsSync(DOCGENCONFIG_PATH)) { throw new Error(`${DOCGENCONFIG_PATH} does not exist`); }
+
+const PACKAGEJSON = JSON.parse(fs.readFileSync(PACKAGEJSON_PATH));
+const DOCGENCONFIG = getDocgenConfig();
+const TSCONFIG_ORIG = JSON.parse(fs.readFileSync(TSCONFIG_PATH));
+const TSCONFIG_COPY = _.cloneDeep(TSCONFIG_ORIG);
+
+const cleanupFns = [];
 
-function getTypedocConfig() {
-  const file = ['./typedoc.json', 'tsconfig.typedoc.json'].find((filename) =>
-    fs.existsSync(filename)
-  );
-  const config = JSON.parse(fs.readFileSync(file));
-  const requiredKeys = ['typedoc', 'typedoc.generateOptions'];
-  const missing = requiredKeys.find((key) => !has(config, key));
+// Merge tsconfig block from docgen.json into tsconfig.json
+_.defaultsDeep(TSCONFIG_COPY, DOCGENCONFIG.tsconfig);
+fs.writeFileSync(TSCONFIG_PATH, JSON.stringify(TSCONFIG_COPY, null, 2));
+cleanupFns.push(() => fs.writeFileSync(TSCONFIG_PATH, JSON.stringify(TSCONFIG_ORIG, null, 2)));
+shelljs.cat(TSCONFIG_PATH);
+
+function getDocgenConfig() {
+  const config = JSON.parse(fs.readFileSync(DOCGENCONFIG_PATH));
+  const requiredKeys = ['navigation', 'tsconfig'];
+  const missing = requiredKeys.find((key) => !_.has(config, key));
   if (missing) {
-    console.error(`${file} does not contain configuration key: '${missing}'`);
+    console.error(`${DOCGENCONFIG_PATH} does not contain configuration key: '${missing}'`);
     process.exit(1);
   }
   return config;
@@ -33,51 +48,31 @@ function getTypedocConfig() {
 // Register hook to cleanup temp directories
 nodeCleanup(() => {
   util.packageDir();
-  process
-    .exit(0)(TYPEDOC_CONFIG.typedoc.include || [])
-    .forEach((include) => {
-      const pkg = include.package.split('/').shift();
-      console.log(`(not) removing temporary directory ./${pkg}...`);
-      shelljs.rm('-rf', package);
-    });
+  if (!options.noclean) {
+    cleanupFns.forEach(fn => fn());
+  }
 });
 
 // Fetch all included packages (i.e., core module)
-const includes = TYPEDOC_CONFIG.typedoc.include || [];
+const includes = DOCGENCONFIG.include || [];
 includes.forEach((include) => {
-  const { branch, package: pkg, repo } = include;
-  const flags = {
-    noBuild: true,
-    noPublish: true,
-    noInstall: true,
-    branch: branch,
-  };
+  const { pkg, repo } = include;
+  const semver = ['peerDependencies', 'dependencies', 'devDependencies']
+    .map((key) => (PACKAGEJSON[key] || {})[pkg])
+    .find((x) => !!x);
 
-  if (!branch) {
-    const semver = ['dependencies', 'peerDependencies', 'devDependencies']
-      .map((key) => (PACKAGE_JSON[key] || {})[pkg])
-      .find((x) => !!x);
-    const version = findSemverPackage(pkg, semver);
-    flags.branch = version ? version : flags.branch;
+  const INSTALLDIR = `${SRC_DIR}/${pkg}`;
+  shelljs.mkdir('-p', INSTALLDIR);
+  if (!fs.existsSync(path.join(INSTALLDIR, '.git'))) {
+    _exec(`git clone ${repo} ${INSTALLDIR}`);
+    cleanupFns.push(() => shelljs.rm('-rf', INSTALLDIR));
   }
 
-  console.log(`fetching ${repo} to temporary directory ${pkg}`);
-  _exec(`mkdir -p ${pkg}`);
-  publishYalcPackage(pkg, repo, flags);
+  const version = findSemverPackage(pkg, semver);
+  shelljs.pushd(INSTALLDIR)
+  _exec(`git checkout ${version}`);
+  shelljs.popd()
 });
 
-// create command line
-const typedocOptions = TYPEDOC_CONFIG.typedoc.generateOptions || {};
-typedocOptions.out = path.join(PACKAGE_DIR, typedocOptions.out || '_doc');
-
-const cmdLineOpts = Object.keys(typedocOptions)
-  .map((key) => `--${key} ${typedocOptions[key]}`)
-  .join(' ');
-
-const files = []
-  .concat(TYPEDOC_CONFIG.files || [])
-  .concat(TS_CONFIG.files)
-  .concat(includes.map((x) => './' + path.join(x.package, x.entry)));
-
 // run typedoc command
-_exec(`npx typedoc ${cmdLineOpts} ${files.join(' ')}`);
+_exec(`npx typedoc`);

package.json

@@ -28,8 +28,12 @@
     "test_downstream_projects": "./test_downstream_projects.js",
     "util": "./util.js"
   },
+  "peerDependencies": {
+    "typedoc": "~0.17.7",
+    "typedoc-plugin-ui-router": "^3.0.1"
+  },
   "dependencies": {
-    "check-peer-dependencies": "2.0.2",
+    "check-peer-dependencies": "^2.0.2",
     "conventional-changelog": "^3.1.21",
     "conventional-changelog-ui-router-core": "^1.4.2",
     "find-parent-dir": "^0.3.0",
@@ -43,11 +47,6 @@
     "shx": "^0.3.1",
     "tmp": "^0.2.1",
     "tweak-sourcemap-paths": "0.0.4",
-    "typedoc": "^0.17.7",
-    "typedoc-plugin-external-module-name": "3.1.0",
-    "typedoc-plugin-internal-external": "2.1.1",
-    "typedoc-plugin-ui-router": "2.0.2",
-    "ui-router-typedoc-themes": "1.0.2",
     "yalc": "^1.0.0-pre.35",
     "yargs": "^15.3.1"
   },

publish_docs.js

@@ -10,23 +10,24 @@ const _exec = util._exec;
 const sh = require('shelljs');
 const readlineSync = require('readline-sync');
 
-const CONFIG = JSON.parse(fs.readFileSync('./typedoc.json'));
+const CONFIG = JSON.parse(fs.readFileSync('./docgen.json'));
+const TYPEDOC_CONFIG = JSON.parse(fs.readFileSync('./typedoc.json'));
 const pkg = JSON.parse(fs.readFileSync('./package.json'));
 const version = pkg.version;
 
 const GIT_URL = "[email protected]:ui-router/ui-router.github.io.git";
 const installTargetDir = path.join(".downstream_cache", "ui-router.gihub.io");
-const PAGES_DIR = path.join(installTargetDir, CONFIG.typedoc.publishDir);
+const PAGES_DIR = path.join(installTargetDir, CONFIG.publishDir);
 
 publishYalcPackage(installTargetDir, GIT_URL, { noInstall: true, noBuild: true, noPublish: true });
 
 util.packageDir();
 
 sh.rm('-rf', path.join(PAGES_DIR, 'latest'));
-sh.cp('-r', CONFIG.typedoc.generateOptions.out, path.join(PAGES_DIR, 'latest'));
+sh.cp('-r', TYPEDOC_CONFIG.out, path.join(PAGES_DIR, 'latest'));
 
 sh.rm('-rf', path.join(PAGES_DIR, version));
-sh.cp('-r', CONFIG.typedoc.generateOptions.out, path.join(PAGES_DIR, version));
+sh.cp('-r', TYPEDOC_CONFIG.out, path.join(PAGES_DIR, version));
 
 sh.cd(PAGES_DIR);
 _exec("./process_docs.sh");