feat(docgen): Create a docker image uirouter:docgen which generates docs so projects do not need a direct dependency on typedoc

Author: christopherthielen

docgen/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:12
+
+RUN apt-get update && apt-get install -y rsync jq vim
+
+WORKDIR /home/node/work
+COPY package.json /home/node/work
+RUN npm install
+RUN sed -i'' -e 's/Globals/{{name}}/' node_modules/typedoc-default-themes/bin/default/partials/breadcrumb.hbs
+
+COPY clone.sh /home/node/work
+COPY docgen.sh /home/node/work
+COPY prep_docgen.js /home/node/work
+COPY findSemverPackage.js /home/node/work
+
+ENTRYPOINT ["/home/node/work/docgen.sh"]

docgen/clone.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+REPO=$1
+DIR=$2
+BRANCH=$3
+
+mkdir -p $DIR
+git clone $REPO $DIR
+cd $DIR
+git checkout $BRANCH

docgen/docgen.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -ex
+
+WORK=/home/node/work
+PROJECT=${WORK}/project
+
+[[ -d $PROJECT ]] || {
+  echo "package must be mounted in Docker at $PROJECT"
+  exit 1
+}
+
+[[ -e $PROJECT/package.json ]] || {
+  echo "package must be mounted in Docker at $PROJECT"
+  exit 1
+}
+
+pushd $WORK
+cp $WORK/project/docgen.json .
+cp $WORK/project/typedoc.json .
+README=$(jq -r .readme < typedoc.json)
+cp $WORK/project/$README .
+
+./prep_docgen.js
+bash ./clone_repos.sh
+npx typedoc

docgen/docker_push.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+docker build -t docgen . --no-cache
+docker tag docgen:latest uirouter/docgen:stable
+docker push uirouter/docgen:stable
+

docgen/findSemverPackage.js

@@ -0,0 +1,2 @@
+const child_process = require('child_process');
+

docgen/package.json

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "lodash": "^4.17.19",
+    "find-parent-dir": "^0.3.0",
+    "typedoc": "0.17.8",
+    "typescript": "3.9.7",
+    "typedoc-plugin-ui-router": "3.0.2"
+  }
+}

docgen/prep_docgen.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const childProcess = require('child_process');
+const _ = require('lodash');
+
+const WORKDIR = process.cwd();
+const PACKAGE_DIR = `${WORKDIR}/project`;
+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`;
+
+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_COPY = JSON.parse(fs.readFileSync(TSCONFIG_PATH).toString());
+
+// Merge tsconfig block from docgen.json into tsconfig.json
+_.merge(TSCONFIG_COPY, DOCGENCONFIG.tsconfig);
+fs.writeFileSync(`${WORKDIR}/tsconfig.json`, JSON.stringify(TSCONFIG_COPY, null, 2));
+
+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(`${DOCGENCONFIG_PATH} does not contain configuration key: '${missing}'`);
+    process.exit(1);
+  }
+  return config;
+}
+
+// Fetch all included packages (i.e., core module)
+const CLONE_COMMANDS = ['#!/usr/bin/env bash', 'set -x'];
+
+(DOCGENCONFIG.include || []).forEach(include => {
+  const { pkg, repo, branch } = include;
+  const semver = ['peerDependencies', 'dependencies', 'devDependencies']
+    .map((key) => (PACKAGEJSON[key] || {})[pkg])
+    .find((x) => !!x);
+
+  const version = branch || findSemverPackage(pkg, semver);
+  CLONE_COMMANDS.push(`./clone.sh ${repo} ${PACKAGE_DIR}/src/includes/${pkg} ${version}`);
+});
+
+fs.writeFileSync('clone_repos.sh', CLONE_COMMANDS.join('\n'));
+
+// Finds the newest version of a package published to NPM that matches the desired semver range
+function findSemverPackage(packageName, semver) {
+  const stdout = childProcess.execSync(`npm info ${packageName}@${semver} version`).toString();
+  const lines = stdout.split(/\n/).filter(x => x.length);
+  if (lines.length === 0) {
+    throw new Error(`No published package matched ${packageName}@${semver}`)
+  } else if (lines.length === 1) {
+    return lines[ 0 ];
+  } else {
+    const line = stdout.trim().split(/\n/).pop().trim();
+    const [, version] = /.* '(.*)'$/.exec(line) || [];
+    if (!version) {
+      console.log({ stdout, line });
+      throw new Error(`Couldn't find version matching ${packageName}@${semver} in npm registry`)
+    }
+    return version;
+  }
+}